Purpose

To retrieve an access token which represents the authorization to your application to access the other API services.

Process summary

On this page you will find the following

1 Purpose
- 1.1 Process summary
2 Initial token retrieval
- 2.1 Client Credentials
  - 2.1.1 Response
    - 2.1.1.1 Response message format
- 2.2 Authorization Code
  - 2.2.1 Exchange the Authorization Code for an Access Token
- 2.3 Password Grant (deprecated)
  - 2.3.1 Response
    - 2.3.1.1 Response message format
3 Subsequent token refreshes
- 3.1 Response
  - 3.1.1 Response message format

To download the vision diagram on the right you can click below

Initial token retrieval

When integrating we’ll suggest the grant_type to use, in most cases this will be client_credentials. This returns an access_token ready to be used, and also a refresh_token which you can use to refresh the access_token when it expires.

Client Credentials

POST URL: <address>/token

Parameter (x-www-form-urlencoded)

Parameter	Description	Example

Parameter	Description	Example
grant_type	Set to 'client_credentials'	client_credentials
client_id (Username)	The client_id given to you to identify your application, You must ensure that you base64 encode this if it hasn’t been already. (It generally has == at the end when encoded)	assdasd==
client_secret (Password)	The client_secret given to you to identify your application, You must ensure that you base64 encode this if it hasn’t been already. (It generally has == at the end when encoded)	asfsafsa121==

Response

Response message format

{
    "access_token": "sfOlnPVA",
    "token_type": "bearer",
    "expires_in": 86399,
    "refresh_token": "W8mhOR9FlWooICUhToEZw7x6aBVURDFar1g", 
    "client_id": "AKJSLABJ",
    "user_id": "1",
    "InternalServiceAccessOnly": "False",
    ".issued": "Wed, 10 Jun 2020 08:44:41 GMT",
    ".expires": "Thu, 11 Jun 2020 08:44:41 GMT"
}

Key details:

Key	Description	Example

Key

Description

Example

access_token

Your access token

Use this to access the other services

OrDyWqNxG-kEHZVfDXoFe2iwRQAf....

expires_in

Lifetime of the token in seconds

14400

refresh_token

Your refresh token

Use this to refresh your access token after it expires

_p4Jeu1PP9_H6bkeZk9Ew6MdXtR

Authorization Code

URL : https://<address>/Authorize?response_type=code&client_id=123456789&redirect_uri=https://example-app.com/redirect&scope=create_and_delete&state=xcoiv98y2kd22vusuye3kch

URL Parameters

Parameter	Description	Example

Parameter	Description	Example
response_type	response type	code
client_id	client id provided	1234567890
redirect_uri	Registered redirect URL	https://example-app.com/redirect
scope	Access scope	create_and_delete
state	state	xcoiv98y2kd22vusuye3kch

If the user approves the request, the authorization server will redirect the browser back to the redirect_uri specified by the application, adding a code and state to the query string.

Ex: https://example-app.com/redirect?code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3&state=xcoiv98y2kd22vusuye3kch

Exchange the Authorization Code for an Access Token

makes a POST request to the service’s token endpoint(<address>/Token) with the following parameters:

Parameter	Note

Parameter	Note
grant_type	"authorization_code", This tells the token endpoint that the application is using the Authorization Code grant type.
code	The authorization code given in the redirect.
client_id	The application’s client ID.
client_secret	The application’s client secret. This ensures that the request to get the access token is made only from the application, and not from a potential attacker that may have intercepted the authorization code.
redirect_uri	The same redirect URI that was used when requesting the code.

The token endpoint will verify all the parameters in the request, ensuring the code hasn’t expired and that the client ID and secret match. If everything checks out, it will generate an access token and return it in the response!

{
    "access_token": "sfOlnPVA",
    "token_type": "bearer",
    "expires_in": 86399,
    "refresh_token": "W8mhOR9FlWooICUhToEZw7x6aBVURDFar1g", 
    "client_id": "AKJSLABJ",
    "user_id": "1",
    "InternalServiceAccessOnly": "False",
    ".issued": "Wed, 10 Jun 2020 08:44:41 GMT",
    ".expires": "Thu, 11 Jun 2020 08:44:41 GMT"
}

Password Grant (deprecated)

POST URL: <address>/token

Parameter (x-www-form-urlencoded)

Parameter	Description	Example

Parameter	Description	Example
grant_type	Set to 'password'	password
username	Your base64 encoded username	eW91cl91c2VybmFtZQ==
password	Your base64 encoded password	eW91cl9wYXNzd29yZA==
client_id	The client_id given to you to identify your application	b3187e8b1faacfef38641c072b2d8864

Response

Response message format

{
    "access_token": "sfOlnPVA",
    "token_type": "bearer",
    "expires_in": 86399,
    "refresh_token": "W8mhOR9FlWooICUhToEZw7x6aBVURDFar1g", 
    "client_id": "AKJSLABJ",
    "user_id": "1",
    "InternalServiceAccessOnly": "False",
    ".issued": "Wed, 10 Jun 2020 08:44:41 GMT",
    ".expires": "Thu, 11 Jun 2020 08:44:41 GMT"
}

Key details:

Key	Description	Example

Key

Description

Example

access_token

Your access token

Use this to access the other services

OrDyWqNxG-kEHZVfDXoFe2iwRQAf....

expires_in

Lifetime of the token in seconds

14400

refresh_token

Your refresh token

Use this to refresh your access token after it expires

_p4Jeu1PP9_H6bkeZk9Ew6MdXtR

Subsequent token refreshes

Refreshing the access token

POST URL: <address>/token

Parameter (x-www-form-urlencoded)

Parameter	Description	Example

Parameter	Description	Example
grant_type	Set to 'refresh_token'	refresh_token
refresh_token	The refresh_token generated for you in the access_token request	_p4Jeu1PP9_H6bkeZk9Ew6MdXtR
client_id	The client_id given to you to identify your application	b3187e8b1faacfef38641c072b2d8864

Response

Response message format

Key details:

Key	Description	example

Key

Description

example

access_token

Your new access token

Use this to access the other services

OrDyWqNxG-kEHZVfDXoFe2iwRQAf....

Obtaining the Token

Purpose

Process summary

Initial token retrieval

Client Credentials

Response

Response message format

Authorization Code

Exchange the Authorization Code for an Access Token

Password Grant (deprecated)

Response

Response message format

Subsequent token refreshes

Response

Response message format