Requesting an access token

The Access Token is required in the header of every request to the API. You must request an Access Token which lasts for a limited amount of time. An Access Key is required to request a new Access Token, as per RFC7617.

Creating an access key

An Access Key is unique to your tenant and should be kept safe and used each time you need to request an Access Token.

The Access Key is made up of the Client Key and Client Secret combined...

E.g.

Client Key = "12345678901234567890"
Client Secret = "abcdefghijklmnopqrs"

Combine as a single string separated by a colon ":"...

12345678901234567890:abcdefghijklmnopqrs

Encoded with Base64 format to create the Access Key.

MTIzNDU2Nzg5MDEyMzQ1Njc4OTA6YWJjZGVmZ2hpamtsbW5vcHFycw==

Online Tool for Base64 Encoding (opens in a new window/tab)

This encoded string can be decoded to retrieve the Client Key and Client Secret so must be kept safe.

Requesting an access token

The Access Token is requested using your Access Key. The token is short lived and can change each request for security.

 curl -X POST https://api.iris.co.uk/oauth2/v1/token \
   -H "Content-Type: application/x-www-form-urlencoded" \
   -H "authorization: Basic <access_key>" \
   -d "grant_type=client_credentials"

The response from IRIS will be a JSON message containing the following:

 {
      "access_token": "4gYpTokCeSHyIdMJFv84jY5yrzKO",
      "expires_in": "3599",
      "scope": "",
      "token_type": "Bearer"
   }

Understanding the scopes

As part of the returned response, it will also define what scope the used key is for.

If you are using a key that has full Read / Write permissions, the returned response is:

   {
      "access_token": "4gYpTokCeSHyIdMJFv84jY5yrzKO",
      "expires_in": "3599",
      "scope": "iris.hr.write iris.hr.read",
      "token_type": "Bearer"
   }

If you are using a key that has Read Only permissions, the returned response is:

   {
      "access_token": "4gYpTokCeSHyIdMJFv84jY5yrzKO",
      "expires_in": "3599",
      "scope": "iris.hr.read",
      "token_type": "Bearer"
   }

If you try to use the wrong key when triggering POST, PUT and DELETE operations you will receive a 403 Forbidden error as per this example:

    {
      "code": "403-000-0001",
      "description": "The resource requires scopes that are not included in the access token.",
      "log_trace": "rrt-6269014584192592964-b-geu2-1879108-112404252-2"
    }