Docs

Refresh Tokens

Versioncurrent

A Refresh Token contains the information required to obtain a new Access Token or ID Token.

Typically, a user needs a new Access Token when gaining access to a resource for the first time, or after the previous Access Token granted to them expires.

Refresh Tokens:

  • Are subject to strict storage requirements to ensure that they are not leaked
  • Can be revoked by the Authorization Server

OIDC-conformant applications

The behavior in this document is applicable to OIDC-conformant applications. You can configure an application to be OIDC-conformant in one of the following two ways:

  1. Enabling the OIDC Conformant flag for an Application
  2. Passing an audience to the /authorize endpoint of the Authentication API

For more information on our authentication pipeline, see Introducing OIDC-Conformant Authentication.

Overview

Auth0 can issue an Access Token and/or an ID Token in response to an authentication request. You can use Access Tokens to make authenticated calls to a secured API, while the ID Token contains user profile attributes represented in the form of claims. Both are JWTs and therefore have expiration dates indicated using the exp claim, as well as security measures, like signatures.

A Refresh Token allows the application to ask Auth0 to issue a new Access Token or ID Token without having to re-authenticate the user. This will work as long as the Refresh Token has not been revoked.

Restrictions on Refresh Token Usage

You can only get a Refresh Token if you are implementing the Authorization Code Flow, Authorization Code Flow with Proof Key for Code Exchange (PKCE), Resource Owner Password Grant, or Device Authorization Flow.

A Single-Page Application (normally implementing Implicit Flow) should not ever receive a Refresh Token. A Refresh Token is essentially a user credential that allows a user to remain authenticated indefinitely. This sensitive information should be stored securely and not exposed client-side in a browser.

If you are implementing an SPA using Implicit Flow and you need to renew a token, the only secure option for doing so is to use Silent Authentication.

If you limit offline access to your API, a safeguard configured via the Allow Offline Access switch on the API Settings, Auth0 will not return a Refresh Token for the API (even if you include the offline_access scope in your request).

Get a Refresh Token

To get a Refresh Token, you must include the offline_access scope when you initiate an authentication request through the authorize endpoint.

For example, if you are using the Authorization Code Flow, the authentication request would look like the following:

Once the user authenticates successfully, the application will be redirected to the redirect_uri, with a code as part of the URL: https://YOUR_APP/callback?code=BPPLN3Z4qCTvSNOy. You can exchange this code with an Access Token using the /oauth/token endpoint.




The response should contain an Access Token and a Refresh Token.

If you are requesting a Refresh Token for a mobile app using the corresponding Native Client (which is public), then you don't need to send the client_secret in the request since it's only required for confidential applications.

Refresh Tokens must be stored securely by an application since they allow a user to remain authenticated essentially forever.

For more information on how to implement this using the Authorization Code Flow, refer to our tutorial, Call API Using the Authorization Code Flow. For other grants, see API Authorization.

If the response did not include a Refresh Token, check that you comply with the Restrictions listed in this document.

Use a Refresh Token

To exchange the Refresh Token you received during authorization for a new Access Token, make a POST request to the /oauth/token endpoint in the Authentication API, using grant_type=refresh_token.




Parameter Description
grant_type The type of grant to execute (the /token endpoint is used for various grants, for more information refer to the Authentication API). To refresh a token, use refresh_token
client_id Your application's Client ID
client_secret Optional. Your application's Client Secret. Only required for confidential applications
refresh_token The Refresh Token to use

The response will include a new Access Token, its type, its lifetime (in seconds), and the granted scopes. If the scope of the initial token included openid, then a new ID Token will be in the response as well.

Rate limits

You should only ask for a new token if the Access Token has expired or you want to refresh the claims contained in the ID Token. For example, it's a bad practice to call the endpoint to get a new Access Token every time you call an API. There are rate limits in Auth0 that will throttle the number of requests to this endpoint that can be executed using the same token from the same IP.

Revoke a Refresh Token

Since Refresh Tokens never expire, it is essential to be able to revoke them in case they get compromised.

For the Device Authorization Flow, the only way to force a device to reauthorize is to revoke the Refresh Token assigned to the device. To learn how, see Unlink Devices from Users. Note that the device will not be forced to reauthorize until the current Access Token expires and the application tries to use the revoked Refresh Token.

Auth0 handles token revocation as though the token has been potentially exposed to malicious adversaries. Therefore, each revocation request invalidates not only the specific token, but all other tokens based on the same authorization grant. This means that all Refresh Tokens that have been issued for the same user, application, and audience will be revoked.

You can revoke a Refresh Token by:

Use the Authentication API

To revoke a Refresh Token, you can send a POST request to https://YOUR_DOMAIN/oauth/revoke.

The API first validates the application credentials and then verifies whether the token was issued to the application making the revocation request. If this validation fails, the request is refused, and the application is informed of the error. Next, the API invalidates the token. The invalidation takes place immediately, and the token cannot be used again after the revocation. Each revocation request invalidates all the tokens that have been issued for the same authorization grant.




Where:

Parameter Description
client_id
Required
Your application's Client ID. The application should match the one the Refresh Token was issued for.
client_secret Your application's Client Secret. Required for confidential applications.
token
Required
The Refresh Token you want to revoke.

The application should match the one for which the Refresh Token was issued.

Revoke a token without the Client Secret

For applications that cannot keep the Client Secret safe (e.g., native apps), the Revoke endpoint supports access without the Client Secret. However, the application itself must have the property tokenEndpointAuthMethod set to none. You can change the tokenEndpointAuthMethod value, either from the UI (Dashboard > Clients > Application Settings), or using the Management API.

If the request is valid, the Refresh Token is revoked, and the response is HTTP 200, with an empty response body. Otherwise, the response body contains the error code and description.

The possible responses are:

HTTP Status Description
200 The Refresh Token is revoked, does not exist, or was not issued to the application making the revocation request. The response body is empty.
400 The required parameters were not sent in the request ("error": "invalid_request").
401 The request is not authorized ("error": "invalid_client"). Check that the application credentials (client_id and client_secret) are present in the request and hold valid values.

Use the Management API

To revoke a Refresh Token using the Auth0 Management API, you need the id of the Refresh Token you wish to revoke. To obtain a list of existing Refresh Tokens, call the List device credentials endpoint, specifying type=refresh_token with an Access Token containing read:device_credentials scope. To narrow the results, you can also specify the client_id and user_id associated with the token (if known).

Response body:

To revoke a Refresh Token, call the Delete a device credential endpoint with an Access Token containing delete:device_credentials scope and the value of id obtained above:

The response will be an HTTP 204: The credential no longer exists.

Use the Dashboard

Strictly speaking, the following process shows you how to revoke a user's authorized access to the application that issued the token. This renders the Refresh Token invalid, which is functionally identical to revoking the token itself.

To do this, go to the Users section of the dashboard. Click the name of the user to view their Details page.

Select the Authorized Applications tab. This page lists all the applications to which the user has authorized access. Revoking an authorized application also revokes its associated Refresh Tokens.

To revoke the user's access to an authorized application, and hence invalidate the Refresh Token, click Revoke.

Revoke a Refresh Token using the dashboard

Rules

Rules will run for the Refresh Token Exchange. To execute special logic, you can look at the context.protocol property in your rule. If the value is oauth2-refresh-token, then this is the indication that the rule is running during the Refresh Token Exchange.

If you try to do a redirect with context.redirect, the authentication flow will return an error.

SDK Support

Web Apps

All our main SDKs support Refresh Tokens out of the box. Some are Node.js, ASP.NET Core, PHP, Java, and many more. For a complete listing, see Quickstarts.

Single-Page Apps

Silent Authentication is the method that is used to refresh a token for web apps that execute in a browser. Auth0.js, our client-side library, provides methods for this functionality:

  • The authorize method, redirects the user to the /authorize endpoint, to log in and provide consent.
  • The parseHash method, parses a URL hash fragment to extract the result of an Auth0 authentication response.
  • The checkSession method, attempts to get a new token from Auth0, using silent authentication. For more details refer to Using checkSession to Acquire New Tokens.

Mobile / Native Apps

For information on using Refresh Tokens with our mobile SDKs, see:

Next steps