Configure Refresh Token Expiration

Refresh tokens can be a target for abuse if leaked because they can be used to acquire new access tokens. Although Refresh Token Rotation and Automatic Reuse Detection can help mitigate this risk, Auth0 recommends that you issue a refresh token that expires after a preset lifetime. The refresh token expiration lifetime can be extended each time the refresh token is used so that the user gets a new access token or refresh token/access token pair (in the case of rotating refresh tokens).

You can enable and configure two refresh token lifetime settings, absolute and inactivity expiration, using either the Auth0 Dashboard or the Auth0 Management API. You can use a combination of absolute and inactivity expiration periods to create a balance between security and user experience that suits your business needs.

  • Absolute Lifetime: Set a refresh token or refresh token family lifetime after which the user must re-authenticate before being issued a new access token. If you disable this setting, the absolute lifetime will be indefinite.

  • Inactivity Lifetime: Set the inactivity lifetime of issued refresh tokens to expire if the user is not active in your application during a specified period.

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 Expiration, enable Absolute Expiration. When enabled, a refresh token will expire based on an absolute lifetime, after which the token can no longer be used. If rotation is enabled, an expiration lifetime must be set.

    The Absolute Expiration of the rotating refresh token is defined on creation and is not changed, even with an exchange.

    Dashboard Applications Applications Settings Tab Refresh Token Expiration

  5. Enter Absolute Lifetime in seconds. The refresh token expires after the specified interval and can no longer be used to get a new access token. When rotation is enabled, the absolute expiration also applies to the ability to get new tokens.

    Value
    Default 2,592,000 seconds (30 days)
    Minimum 1 second
    Maximum 31,557,600 seconds (1 year)

    The calculation for 1 year is equivalent to 365.25 days to account for leap years.

  6. Enable Inactivity Expiration. When enabled, a refresh token will expire based on a specified inactivity lifetime, after which the token can no longer be used.

  7. Enter Inactivity Lifetime in seconds. If the refresh token is not exchanged within the specified interval, the refresh token expires and can no longer be used to get a new access token. The expiration period is renewed each time the refresh token is exchanged for a new access token within the interval.

    Value
    Minimum 1 second
    Maximum 31,557,600 seconds (1 year)

  8. Click Save Changes.

Configure with the Management API

You can configure the absolute and inactivity lifetime settings in the payload for the Management API /api/v2/clients/{id} endpoint. Here is an example that sets expiration lifetime for a non-rotating refresh token:

PATCH /api/v2/clients/{id}
{
  "refresh_token": {
      "rotation_type": "non-rotating",
      "expiration_type": "expiring",
      "token_lifetime": 2592000,
      "infinite_token_lifetime": false,
      "idle_token_lifetime": 604800,
      "infinite_idle_token_lifetime": false
  }
}

Support and limitations

The OAuth BCP states that refresh tokens issued for browser-based applications must have an expiration and either enforce sender-constraint or rotate tokens with each request. Therefore, SPAs will default into rotation and will not support non-expiring refresh tokens.

Learn more