Refresh Token

Heads up! If you are working with the API Authorization flows and you are looking for the updated documentation, refer to Refresh Token (API Authorization).

A Refresh Token is a special kind of token 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.

Usually, a user will need a new access token only after the previous one expires, or when gaining access to a new resource for the first time.

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.

Refresh tokens can be obtained or revoked programmatically through the Auth0 API. They can also be viewed and revoked from the dashboard.

Refresh tokens are subject to strict storage requirements to ensure that they are not leaked.

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/?
    response_type=token
    &client_id=YOUR_CLIENT_ID
    &redirect_uri=YOUR_CALLBACK_URL
    &state=VALUE_THAT_SURVIVES_REDIRECTS
    &scope=openid%20offline_access
    &device=my-device

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:

GET https://YOUR_CALLBACK_URL#
    access_token=2nF...WpA
    &id_token=eyJhb...
    &state=VALUE_THAT_SURVIVES_REDIRECTS
    &refresh_token=Cqp...Mwe

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

Security Warning

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

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. 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?
  type=refresh_token
  &client_id={}
  &user_id={}

{
  "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.

Revoke a Refresh Token in the Dashboard

Click UNLINK to confirm.