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
Table of Contents | ||
---|---|---|
|
To download the vision diagram on the right you can click below
View file | ||
---|---|---|
|
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 |
---|---|---|
grant_type | Set to 'client_credentials' | client_credentials |
client_id | 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 | 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
Code Block | ||
---|---|---|
| ||
{ "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 |
---|---|---|
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 |
Expand | |||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||
Authorization CodeURL : https://<address>/Authorize?response_type=code&client_id=123456789&redirect_uri=https://example-app.com/redirect&scope=create_and_delete&state=xcoiv98y2kd22vusuye3kch URL Parameters
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 Tokenmakes a POST request to the service’s token endpoint(<address>/Token) with the following parameters:
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!
|
Expand | ||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||
Password Grant (deprecated)POST URL: <address>/token Parameter (x-www-form-urlencoded)
ResponseResponse message format
Key details:
|
Subsequent token refreshes
POST URL: <address>/token
Parameter (x-www-form-urlencoded)
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
Code Block | ||
---|---|---|
| ||
{ "access_token": "XKV31w5gTaKAM9eTI8klFB-3yv9w2TzwCA-XPtOjnHFVR4Z", "token_type": "bearer", "expires_in": 119999, ".issued": "Mon, 04 Mar 2019 10:17:44 GMT", ".expires": "Tue, 05 Mar 2019 19:37:44 GMT" } |
Key details:
Key | Description | example |
---|---|---|
access_token | Your new access token Use this to access the other services | OrDyWqNxG-kEHZVfDXoFe2iwRQAf.... |