Authentication and Authorisation

Authentication

Every request to the Data API expects an “authorization header” containing a “bearer token” (JWT) which authenticates calling clients or users. The token must be generated prior to calling the API, using the OAuth2 client credentials flow against the Kalibrate client authentication Endpoint.

The Endpoint in use depends on whether the client is connecting to one of the test environments or “production”.

To authenticate, clients must send a “post” request to the Authentication Endpoint, and the body of the request must contain the authentication parameters (with the body content type set to x-www-form-urlencoded).

Param	Description
client_id	A Kalibrate provided client identifier that uniquely identifies the client making the API request. Each customer (tenant) may have multiple credentials (with potentially different access rights) to access their data. A single client may connect to multiple test environments. Only product client identifiers may connect to production data (and these are issued from a different identity provider instance).
client_secret	A key that can be used to authenticate the client against the authentication Endpoint (as password). These are issued by Kalibrate and periodically rotated to ensure security of the data in the Data API
grant_type	OAuth2 Grant Type. Must be set to client_credentials
scope	A customer unique resource identifier that is used to authorize the calling client for access to specific data. It is possible for a client to have access to multiple resources (databases), for example where a customer has a multiple customer tenant configuration.

Token Request Example

The following RAW HTTP example shows the POST request to the microsoft AD Tenant requesting an access token:

POST / HTTP/1.1
Host: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=0525B217-CBB9-4D4A-B8A1-7551C30098CF
&client_secret=1234
&grant_type=client_credentials
&scope={scope}

Token Response Example

The output result is a JSON document containing the authorisation details:

{
    "token_type":"Bearer",
    "expires_in":3599,
    "ext_expires_in":3599,
    "access_token":"abcefgh...."
}

The most important element being the access_token which must be provided as an Authorization header with every request to the data API.

Access token's retrieved this way cannot be refreshed. Once they timeout (3599 seconds) a new token must be requested in the same fashion as the original request.

Authorisation

The Data API uses the provided authentication token to perform authorization internally against a calling client, to ensure that the client can perform the requested operation.

In the current version of the Data API, we have implemented only “coarse-grained” access control, i.e. an authorized client can read any data (for their authorized tenant) or ReadWrite any data, from any of the Endpoints.

Future iterations of the API may include more “fine-grained” access control.