Overview

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:

📘

An example of token endpoint payload

grant_type=refresh_token&refresh_token=AXXtUZBWvfee7KSiSL98RwhYtNwEMhaswN7LkySYPXoUneYmi8mny4AzmtpRvs6dcK&client_id=plbDrF3shSTQooL

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:

📘

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: