Refresh token grant
This article describes what refresh tokens are and how they are used in Authorization Control Plane (ACP)
Refresh tokens in a nutshell
Refresh tokens are issued to a client application by ACP and can be used to obtain new access tokens when a previous access token expires or becomes invalid. A new token can have an identical or narrower scope. By design, refresh tokens are long-lived, but they can also expire. Additionally, they are single-use only. Every time a refresh token is used to request access tokens, a new refresh token is issued and the previous token is invalidated.
Warning
Because of the long lifetime of refresh tokens, you need to be able to store them in a secure manner. It is also possible to revoke a refresh token. Make sure that you handle refresh tokens securely and prevent them from getting leaked.
Refresh tokens can be used, for example, to improve the authentication experience for native applications. In this case, the user has to authenticate only once, as any next authentication can be achieved using the refresh token without any action from the user.
Simplified flow diagram
Refresh token grant in depth
Refresh token grant can be conceived as an extension of the authorization code grant flow, rather than a separate OAuth flow.
To use the refresh token grant in ACP, you have to enable the grant in your Workspace Settings > Authorization and add an Offline access scope in Applications > Your application > Scopes > Profile.
Every time you make a request to the authorize
endpoint using the authorization code grant
flow with the
offline_access
scope parameter, you receive both an access token and a refresh token. You can use
the provided refresh token to obtain a new access token using the refresh token grant flow.
Refresh tokens can be used only once to obtain a new access token.
When the application requests a new access token, it also receives a new refresh token for later use.
Flow diagram
How the flow works
-
The client uses the authorization code grant flow and includes the
offline_scope
parameter in the request to theauthorize
endpoint.Result
As the result of the client authentication, the client receives an access token and a refresh token.
-
The client requests protected resources from the resource server and submits its access token.
-
The resource server validates the request and responds with requested resources.
-
The access token expires.
-
The client requests protected resources from the resource server and submits its access token.
Result
The resource server validates the request and, as the access token presented in the request had expired, it responds with the
Invalid token
error.Tip
Without the use of refresh tokens, at this point, it would be required to authenticate the client again to obtain a new access token.
-
The client makes a request to the
token
endpoint and provides its refresh token as the value of therefresh_token
parameter. -
ACP validates the request.
-
ACP returns a new access token and a new refresh token.
-
The client requests protected resources from the resource server and submits the access token it received in the previous step.
-
The resource server validates the token and responds with requested resources.