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.
- Are subject to strict storage requirements to ensure that they are not leaked
- Can be revoked by the Authorization Server
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:
- Enabling the OIDC Conformant flag for an Application
- Passing an
/authorizeendpoint of the Authentication API
For more information on our authentication pipeline, see Introducing OIDC-Conformant Authentication.
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 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
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
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.
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
||The type of grant to execute (the
||Your application's Client ID|
|client_secret||Optional. Your application's Client Secret. Only required for confidential applications|
||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.
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:
- Posting a request to the Authentication API's /oauth/revoke endpoint
- Posting a request to the Management API's /api/v2/device-credentials endpoint
- Using the dashboard.
Use the Authentication API
To revoke a Refresh Token, you can send a
POST request to
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.
|Your application's Client ID. The application should match the one the Refresh Token was issued for.|
||Your application's Client Secret. Required for confidential applications.|
|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:
|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 (
|401||The request is not authorized (
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
user_id associated with the token (if known).
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.
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.
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.
authorizemethod, redirects the user to the
/authorizeendpoint, to log in and provide consent.
parseHashmethod, parses a URL hash fragment to extract the result of an Auth0 authentication response.
checkSessionmethod, 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: