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

[mermaid-begin]
sequenceDiagram participant Client application participant ACP tenant participant API Client application->>ACP tenant: Refresh token ACP tenant->>Client application: Access token Client application->>API: Request with access token API->>Client application: Response

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

[mermaid-begin]
sequenceDiagram participant Client application participant API participant ACP tenant Client application->>ACP tenant: Authorization grant flow activate Client application activate ACP tenant ACP tenant->> Client application: Access token & refresh token deactivate ACP tenant Client application->>API: Request resources with an access token activate API API->>Client application: Respond with requested resources Client application->>API: Request resources with an access token API->>Client application: Invalid token error deactivate API Client application->>ACP tenant: Refresh token activate ACP tenant ACP tenant->>Client application: New access token and a new refresh token deactivate ACP tenant Client application->>API: Request resources with the new access token activate API API->>Client application: Respond with requested resources deactivate API deactivate Client application

How the flow works

  1. The client uses the authorization code grant flow and includes the offline_scope parameter in the request to the authorize endpoint.

    Result

    As the result of the client authentication, the client receives an access token and a refresh token.

  2. The client requests protected resources from the resource server and submits its access token.

  3. The resource server validates the request and responds with requested resources.

  4. The access token expires.

  5. 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.

  6. The client makes a request to the token endpoint and provides its refresh token as the value of the refresh_token parameter.

  7. ACP validates the request.

  8. ACP returns a new access token and a new refresh token.

  9. The client requests protected resources from the resource server and submits the access token it received in the previous step.

  10. The resource server validates the token and responds with requested resources.