Overview

All Atlas API requests have to be authenticated. The Atlas API supports OAuth2 authentication using the Client Credentials flow.

OAuth2 Client Credentials flow is an industry standard protocol that delivers secure machine-to-machine token based authentication and authorization.

OAuth2

For OAuth2 we support the Client Credentials grant type. This is a security mechanism designed for Machine-to-Machine communication whereby you exchange a ClientId and ClientSecret (think username/password for machines) for an access token by calling the auth/realms/{YOUREREALM}/protocol/openid-connect/token> endpoint. All API calls must supply this access token with Authorization: Bearer as header. For example, with cURL commandline tool, your request would contain something like this:

        curl -H "Authorization: Bearer YourAccessToken" -X GET  "HTTPS://api.is2.app/api/v1/accountreports"
    

These access tokens - also known as bearer tokens have a fixed validity of 1 hour so you’ll have to ask for a new access token using your ClientId and ClientSecret periodically. To simplify implementation for calling applications the bearer token is in a format called a JWT which is a Base64 url encoded JSON object and among other information contains the expiry date and time of the token. This can be used by your application to determine when to request a new token.

    {
... other fields ...,
"exp": 1591193078,
... other fields ...
}

The exp field is in the Seconds Since the Epoch format which is defined as:

A JSON numeric value representing the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date/time, ignoring leap seconds Practically the exp field can be converted into a date easily using the date functions of any programming language.

How often should I get a new access token?

We recommend you obtain a new access token either:

1. When you receive a 401 Unauthorized response from the API
2. or, if this is not possible 5 minutes before the access token is due to expire It is important to get a new access token as infrequently as possible because:
   • Refreshing tokens will transmit your confidential credentials ClientId and ClientSecret which - in the interests of security - should be done as rarely as possible
   • Refreshing tokens requires an additional API call which will slow your application down

Can I refresh my token every request?

We do not recommend refreshing your token every request for the reasons above.

Obtaining a token

You will need your ClientId and ClientSecret to obtain an access token. The ClientId and ClientSecret must be supplied as a Base64 64 encoded Basic authentication string e.g. ClientId:ClientSecret Base64 encoded.

    #!/bin/bash
curl -X POST https://auth.is2.app/auth/realms/{YOUREREALM}/protocol/openid-connect/token \
  -H "Authorization: Basic $(echo -n YourClientId:YourClientSecret | base64)" \
  -d "grant_type=client_credentials"

The API response should look like

    HTTP/1.1 200 OK Content-Type: application/json { "access_token":"1CP9xR6tqpRHzaZxWcFAp3GtkFcXEQ",  "token_type":"Bearer",  "expires_in":3600 }