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 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 and an arbitrary
device name must be included when initiating an authentication request through the authorize endpoint.
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.
Refresh Tokens must be stored securely by an application since they allow a user to remain authenticated essentially forever.
Use a Refresh Token
To obtain a new ID Token, call the delegation endpoint in the Authentication API:
A response from this request could be as follows:
expires_in parameter indicates the lifetime of the new JWT in seconds. It can be calculated by the difference between the
iat claims of the JWT.
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
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 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.