We have introduced the support for Refresh Token in order to align with the modern oAuth standard and to improve our API security.
What is a Refresh Token?
The Refresh token is a long lived and a one-time use only token that is returned by /token and authorize-decoupled/token endpoints along with the access token. The Client uses the Refresh Token to request for a new access token when the old access token is expired using the refresh_token grant type when sending a POST request to our token endpoint.
You can read more about the Refresh Token here.
More information about the changes:
- Existing access tokens will continue to live until they expire.
- New access tokens that are issued will be short lived.
- New refresh token is always issued together with the access token.
- Received refresh token can be used to obtain a new access token.
- Please note that the refresh tokens are long-lived and one-time use only.
- New mandatory parameter grant_type is introduced in the request of /v3/authorize/token
- The value of the parameter is either authorization_code or refresh_token depending on the code being used in the request.
- /v3/authorize-decoupled/token endpoint already had this parameter but the usage of this parameter is now updated and aligned with /v3/authorize/token
- New optional parameter refresh_token is introduced in the request of both endpoints /v3/authorize/token and /v3/authorize-decoupled/token
- This parameter is used to store the refresh token and has to be present when grant_type = refresh_token
- New attribute refresh_token is introduced in the response of both endpoints
- The value of the attribute is the refresh token which can be used to obtain a new access token after its expiry
Why are you keeping the version number still at v3 when introducing changes?
We decided to keep the API version still at v3 as the version is yet not released in Production. Instead we are trying to make sure to inform you well in advance about these changes. We apologize for any inconvenience caused.
Please see the table below for more information (changes highlighted).
Endpoint | As-Is | To-Be | Details |
---|---|---|---|
/v3/authorize/token |
Example request: "code": "{CODE}"
|
Example request using authorization code: "code": "{CODE}" |
grant_type introduced as the Mandatory parameter in the request Available values:
|
|
Example request using refresh token: "refresh_token": "{CODE}" |
refresh_token introduced as the Optional parameter in the request and it is used if grant_type = refresh_token |
|
Example response: JSON {"token_type": "BEARER",
|
Example response: JSON { "token_type": "BEARER", |
access token made short lived (5 min) refresh_token attribute introduced in the response |
|
/v3/authorize-decoupled/token |
Example request: "code": "{CODE}" |
Example request using authorization code: "code": "{CODE}" |
Note that the grant_type parameter was already available in /v3/authorize-decoupled/token but it was missing functionality for refresh token usage. Now this endpoint behaves the same and it is aligned with /v3/authorize/token. |
|
Example request using refresh token: "refresh_token": "{CODE}" |
refresh_token introduced as the Optional parameter in the request and it is used if grant_type = refresh_token | |
Example response: JSON {"token_type": "BEARER", |
access token made short lived (5 min) refresh_token attribute introduced in the response |