Configure Refresh Token Rotation

Configure refresh token rotation for each application using the Dashboard or the Auth0 SPA SDK. When refresh token rotation is enabled, the transition for the user is seamless. The application uses the previous non-rotating refresh token which has expired and swaps it for a rotating refresh token.

Migration scenarios accommodate automatic token revocation when migrating from a non-rotating refresh token to a rotating refresh token and vice-versa.

  • Exchanging a non-rotating refresh token when refresh token rotation is enabled deletes all the non-rotating tokens issued for the same client_id, resource server, and user and tenant.

  • Exchanging a rotating refresh token when refresh token rotation is disabled issues a non-rotating refresh token and revokes the rotating refresh token family.

Configure in the Dashboard

  1. Go to Dashboard > Applications.

  2. Select the application you want to configure.

  3. Go to the Settings tab.

  4. Under Refresh Token Rotation, enable Rotation.

    Dashboard Applications Applications Settings Tab Refresh Token Rotation

  5. Enter Reuse Interval (in seconds) for the refresh token to account for leeway time between request and response before triggering automatic reuse detection. This interval helps to avoid concurrency issues when exchanging the rotating refresh token multiple times within a given timeframe. During the leeway window the breach detection features don't apply and a new rotating refresh token is issued. Only the previous token can be reused; if the second-to-last one is exchanged, breach detection will be triggered.

  6. Click Save Changes.

Refresh Token Rotation is only supported for OIDC-conformant applications having the Refresh Token grant type enabled.

Configure with the Auth0 SPA SDK

You can use the Auth0 SPA SDK to enable refresh token rotation. You must enable offline access and request the offline access scope in the client SDK.

  1. Install the latest version of the auth0-spa-js SDK: npm install @auth0/auth0-spa-js

  2. Enable the feature on the SDK by setting useRefreshTokens: true to start sending the offline_access scope.

        const auth0 = await createAuth0Client({
          domain: '<YOUR AUTH0 DOMAIN>',
          client_id: '<YOUR CLIENT ID>',
          audience: '<YOUR API IDENTIFIER>',
          useRefreshTokens: true
        });
    
    

  3. Configure the Refresh Token rotation settings. For example:

    PATCH /api/v2/clients/{client_id}
        {
          "refresh_token": {
            "rotation_type": "rotating",
            "expiration_type": "expiring",
            "token_lifetime": "2592000",
            "leeway": 3
          }
        }
    
    
    Attribute Description
    rotation_type Text string: "rotating" or "non-rotating"
    expiration_type Text string: "expiring" or "non-expiring"
    token_lifetime The default refresh token expiration period, when Refresh Token Rotation is enabled, is 30 days (2,592,000 seconds). You can configure up to 1 year (31,557,600 seconds). The lifetime does not extend when tokens are rotated.
    leeway Allow the same refresh token to be used within the time period to account for potential network concurrency issues that would otherwise invalidate the token should the client attempt to retry using the same refresh token. By default leeway is disabled. Configurable in seconds.

Automatic reuse detection

If a previously invalidated token is used, the entire set of refresh tokens issued since that invalidated token was issued will immediately be revoked along with the grant, requiring the user to re-authenticate.

Learn more