Authentication

Overview

Xemplo uses OAuth 2.0 for authentication and authorization.

All Xemplo APIs require authentication. Once authenticated you then use your issued bearer token with each API request to authenticate. This token is passed in the Authorization header of your API requests.

Let's break the above statement and understand it step by step.

Getting an Access Token

You first need to register your application with Xemplo to get a Client ID and Client Secret. Currently this is done by contacting Xemplo support and asking for a new Client ID to integrate with our APIs. When doing so, you should specify:

The URL of your Xemplo system
A suitable name and description of the system being integrated
Which APIs are likely to be needed, so they can be granted permission

Using your client ID and secret, you can get an access token using the below endpoint.

Authorization endpoint: https://id.xemplo.com/connect/token.

It accepts a POST request as follows

Required Headers: Content-Type: application/x-www-form-urlencoded

Request Body:

client_id=<your_client_id>
client_secret=<your_client_secret>
grant_type=client_credentials

Code Sample

Below are examples of getting your authentication token using some popular programming languages

const myHeaders = new Headers();  
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");

const urlencoded = new URLSearchParams();  
urlencoded.append("client_id", "YOUR_CLIENT_ID");  
urlencoded.append("client_secret", "YOUR_CLIENT_SECRET");  
urlencoded.append("grant_type", "client_credentials");

const requestOptions = {  
  method: "POST",  
  headers: myHeaders,  
  body: urlencoded,  
  redirect: "follow"  
};

const baseUrl = "https://id.xemplo.com";  
fetch(baseUrl + "/connect/token", requestOptions)  
  .then((response) => response.text())  
  .then((result) => console.log(result))  
  .catch((error) => console.error(error));

var baseUrl = "https://id.xemplo.com";  
var options = new RestClientOptions($"{baseUrl}") { MaxTimeout = -1 };  
var client = new RestClient(options);  
var request = new RestRequest("/connect/token", Method.Post);  
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");  
request.AddParameter("client_id", "YOUR_CLIENT_ID");  
request.AddParameter("client_secret", "YOUR_CLIENT_SECRET");  
request.AddParameter("grant_type", "client_credentials");  
RestResponse response = await client.ExecuteAsync(request);  
Console.WriteLine(response.Content);

Expected Response

With valid credentials, your response should look something like the following JSON response:

{  
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI...",  
  "expires_in": 3600,  
  "token_type": "Bearer",  
  "scope": "hr.read hr.write"  
}

The access_token can then be used until it expires (after 3600 seconds in this particular case).

Calling Xemplo APIs

Add the access token obtained in the previous step in the header of the API request as a Bearer token.

The below code sample fetches company ID 1 via the API.

const myHeaders = new Headers();  
myHeaders.append("Content-Type", "application/json");  
myHeaders.append("Accept", "application/json");  
myHeaders.append("Authorization", "Bearer YOUR_ACCESS_TOKEN");

fetch("https://YOUR_SUBDOMAIN.xemplo.com/api/v1/companies/1")  
  .then((response) => response.text())  
  .then((result) => console.log(result))  
  .catch((error) => console.error(error));

var options = new RestClientOptions("https://YOUR_SUBDOMAIN.xemplo.com")  
var client = new RestClient(options);  
var request = new RestRequest("/api/v1/companies/1");  
request.AddHeader("Content-Type", "application/json");  
request.AddHeader("Accept", "application/json");  
request.AddHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN");

var response = await client.ExecuteAsync(request);