Refresh Token Grant


Refresh Token Grant is meant for obtaining a new valid access token using refresh token that was obtained during initial authentication grant flow stage. It consists a single-step process of:

  1. Use Applixure API credential keypair as authentication using Token endpoint to receive valid access token

You would want to use this grant when the access token's validity (1 hour) has ended, or shortly before, and you still need to continue using the API. Refresh tokens are long-lived and can be used to get new valid access tokens based on the original authorization request.


Scopes are revalidated on refresh

Please note that when obtaining new access token using refresh token, privileges and permissions of the original requesting entity (Applixure user account) are re-validated against scopes granted during initial authorization grant.

This means that if the user account has had its permissions altered since the initial grant, access token returned by Refresh Token Grant may also have narrower set of scopes than access token in use before or it may be denied altogether.

Flow description

Getting updated access token

To receive access token, you will need to send application/x-www-form-urlencoded encoded HTTP request in UTF-8 character set to the token endpoint with following parameters:

ParameterExplanationIs mandatory?
grant_typeMust be set to: refresh_tokenYes
refresh_tokenMust be set to refresh token obtained from initial authorization grant flow.Yes
client_idApplication ID used in initial authorization grant flow.Yes, if request is not authenticated with both Application ID and Application secret (see below).

No, if request is authenticated.
scopeRequested scopes (depending on API being used).

These scopes - if defined - must be equal to or subset of scopes granted for access token in the original authorization grant. New scopes cannot be obtained during refresh token grant flow.


An example of token endpoint payload


You will not need to do authentication for the request if the original authorization used to obtain refresh token was done with the Authorization Code Grant with PKCE flow, which assumes non-confidential, or public, client that cannot hold secret part for Client registration information.

If, however, refresh token was obtained in any other way you must authenticate your client application for the request. Authenticating the client happens by two alternative ways:

  1. Encoding Application ID and Client secret as username and password -parts for HTTP Basic Authentication (authentication information in the HTTP request header)
  2. Adding Application ID and Client secret as parameters to application/x-www-form-urlencoded encoded request body as additional client_id and client_secret parameters (authentication information in the HTTP request body)


HTTP request body authentication NOT RECOMMENDED

As per RFC 6749 Section 2.3.1, authentication using HTTP request body is not recommended and HTTP request header -method should always be favoured instead.

AAS supports both methods but Applixure always recommend using headers for authentication.

Successful call result

If token endpoint call is successful, you will receive JSON formatted payload back with following properties available:

PropertyData typeExplanation
access_tokenstringAccess token.

This is a token to use subsequently for authorizing requests to Applixure APIs.
expires_inintegerValidity time of the access token in seconds from the time of issuance.

Always set to 3600 i.e. 1 hour.

Caller is responsible for tracking lifetime of access tokens it has received for longer time usage and if necessary, refresh it using refresh_token (if present).
refresh_tokenstringRefresh token (if issued).

This is a token to use to obtain a new access token when the lifetime validity of access token expires (see: expires_in). Server may return the same refresh token used in the flow for refresh purposes.

Refresh tokens are valid for 90 days from [original] issuance.
scopestringA space-delimited list of scopes that has been granted for access token.

Please note that depending on the privileges and permissions of the user account that was used to authenticate in phase 1 of the flow, granted scopes may be a subset of the scopes originally requested!
token_typestringAAS always returns tokens of type bearer


An example of success JSON payload

{ "access_token": "2bCL1o2gTwFrsMaSFBK1FbusqfdDUR5J7WyDcci8BkxY4zzQZ7S...", "token_type": "bearer", "expires_in": 3600, "refresh_token": "AXXtUZBWvfee7KSiSL98RwhYtNwEMhaswN7LkySYPXoUneYmi8mny4AzmtpRvs6dcK...", "scope": "account-all:read account-data:manage" }

Error call result

Possible HTTP error response codes returned are:

HTTP Error CodeCondition
400 - Bad RequestNormal error condition when request could not be processed by the token endpoint as per RFC 6749 Section 5.2.

Please inspect returned JSON response body for a reason for call failure.
500 - Internal Server ErrorTemporary error - retry after a while is recommended.

If condition persist, please be in contact with Applixure support for further assistance.
503 - Service UnavailableAAS is temporarily offline - retry after short while is recommended.