Docs

Refresh Tokens

Refresh Tokens

Auth0 issues an Access Token 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. 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.

A Refresh Token is a special kind of token that can be used to obtain a renewed access token. You are able to request new access tokens until the Refresh Token is blacklisted. It’s important that refresh tokens are stored securely by the application because they essentially allow a user to remain authenticated forever.

For native applications, refresh tokens improve the authentication experience significantly. The user has to authenticate only once, through the web authentication process. Subsequent re-authentication can take place without user interaction, using the Refresh Token.

Refresh Tokens can be revoked by the Authorization Server.

OIDC-Conformant Apps

The Refresh Token behavior 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 app.
  2. Passing an audience to the /authorize endpoint of the Authentication API.

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

Restrictions and limitations

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 the rule is running during the exchange.

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

Custom claims

If you have added custom claims to your tokens using a rule, the custom claims will appear in new tokens issued when using a Refresh Token for as long as your rule is in place. Although new tokens do not automatically inherit custom claims, rules run during the Refresh Token flow, so the same code will be executed. This allows you to add or change custom claims in newly-issued tokens without forcing previously-authorized applications to obtain a new Refresh Token.

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. An example is as follows:
auth0.checkSession({
  audience: 'https://mystore.com/api/v2',
  scope: 'read:order write:order'
  }, function (err, authResult) {
    // Renewed tokens or error
});

Native/Mobile apps

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

Keep reading