Refresh Tokens

A refresh token is a special kind of JWT that is used to authenticate a user without them needing to re-authenticate. This is primarily useful for mobile applications that are installed on a device.

For more information on the types of access tokens used by Auth0, see Tokens.

If you are new to refresh tokens, you can learn more about them in this blog post: Refresh Tokens: When to Use Them and How They Interact with JWTs.


The response of an authentication request can result in an id_token (JWT) being issued by Auth0. This token is used to make authenticated calls to a secured API. JWTs have an expiration date indicated by the exp claim (among other security measures, like signing). Applications that are installed locally on a device (such as a desktop or smartphone) may want to avoid asking the user to enter their credentials each time this token expires.

A refresh token allows the application to request Auth0 to issue a new id_token directly, without needing to re-authenticate the user. This will work as long as the refresh token has not been revoked.

Refresh tokens can be issued for each combination of app, user and device. Once the Auth0 refresh token is issued, the values of the client, user, and device set during its creation cannot be changed.

Secure Storage

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

Refresh tokens can be obtained or revoked programmatically through the Auth0 API.

They can also be viewed and revoked from the dashboard.

Obtain a Refresh Token

To obtain a refresh token, the offline_access scope (see: Scopes) and an arbitrary device name must be included when initiating an authentication request through the authorize endpoint.

For example:

GET https://YOUR_AUTH0_DOMAIN/authorize/?

NOTE: The device parameter can be any value, such as a unique mobile device identifier.

When the authentication flow completes, Auth0 will redirect the user to the callback_URL as usual. The complete URL will be as follows:


The refresh token is returned as part of the URL, in the form of an opaque string.

NOTE: In this case, the token was returned to the client directly in the URL because the implicit flow (response_type=token) was used.

Use a Refresh Token

To obtain a new id_token, call the delegation endpoint in the Authentication API:

POST https://YOUR_AUTH0_DOMAIN/delegation
Content-Type: 'application/json'
  "client_id":       "YOUR_CLIENT_ID",
  "grant_type":      "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "refresh_token":   "your_refresh_token",
  "api_type":        "app"

A response from this request could be as follows:

  "token_type": "Bearer",
  "expires_in": 36000,
  "id_token": "eyJ..."

The expires_in parameter indicates the lifetime of the new JWT in seconds. It can be calculated by the difference between the exp and iat claims of the JWT.

Rate limits

Obtaining new tokens using the refresh_token should occur only if the id_token has expired. For example, it is a bad practice to call the endpoint to get a new token every time you call an API. There are rate limits in Auth0 that will throttle the amount 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 important to be able to revoke them.

Revoke a Refresh Token using 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.

GET https://YOUR_AUTH0_DOMAIN/api/v2/device-credentials?

  "Authorization":   "Bearer {your_access_token}"

Response body:

    "id": "dcr_dFJiaAxbEroQ5xxx",
    "device_name": "my-device" // the value of 'device' provided in the /authorize call when creating the token

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:

DELETE https://YOUR_AUTH0_DOMAIN/api/v2/device-credentials/{id}

  "Authorization":   "Bearer {your_access_token}"

The response will be a 204: The credential no longer exists.

Revoke a Refresh Token in the Dashboard

To see if a user has existing devices with associated refresh tokens, go to the Users section of the dashboard. Click the name of the user to view their Details page.

Select the Devices tab. This page lists all device names and the number of refresh tokens associated with each. To revoke a refresh token, click the X to the right of the device name.

Click UNLINK to confirm.

SDK Support

The Lock, auth0.js, and auth0-angular.js libraries include support to obtain and use refresh tokens.

For more information about using refresh tokens with these libraries, see: