Troubleshoot Refresh Token Unknown or Invalid Before Expiry "403: Unknown or invalid refresh token"

Knowledge Articles
1

This article describes why refresh tokens may become invalid before their expiry, leading to errors in production environments. When this occurs, the following error message is returned with an HTTP 403 status code:

Unknown or invalid refresh token.

The full error response body is:

{
    "error": "invalid_grant",
    "error_description": "Unknown or invalid refresh token."
}

Applies To

  • Refresh Token
  • Unknown or Invalid
  • 403 Error

Cause

The error 403: Unknown or invalid refresh token can occur for several reasons:

  1. Token Absolute Lifetime Expiration: The refresh token has passed its configured absolute expiration time. Once this lifetime is reached, the token is permanently invalid, regardless of inactivity periods.
  2. Improper Refresh Token Handling (Custom Logic): Custom application logic that manages refresh tokens outside of standard SDK mechanisms may cause this error. If the custom logic fails to correctly store and use the latest rotated refresh token provided by the server, it might attempt to reuse an older, invalidated token from the same family, triggering the error.
  3. Refresh Token Limit Reached: A limit exists on the number of active refresh tokens per user, per application (e.g., 200). If this limit is exceeded, older tokens may be automatically invalidated and removed by a cleanup process. This cleanup activity can sometimes be identified in logs with entries like "type": "resource_cleanup".
  4. Token Reuse After Rotation: When refresh token rotation is enabled, using an older token invalidates newer tokens within the same family. If an application attempts to use an older token (e.g., due to race conditions, storage issues, or incorrect logic), the request will fail because that specific token (or the entire family) has been invalidated by a previous rotation or reuse. Log entries with "type": "ferrt" often indicate this scenario.
  5. Environmental or Application Failures: Issues during the token refresh process can lead to the application failing to receive or store the new refresh token correctly:
    • Network failures interrupting the response from the authentication server.
    • Device storage failures preventing the new token from being saved.
    • Application crashes or unexpected closures during the refresh token exchange.

Solution

Perform the following steps and checks to resolve and prevent this error:

  1. Token Absolute Lifetime Expiration:

    • The primary resolution when encountering an invalid refresh token is to initiate a new authentication flow. This will issue a fresh set of tokens, including a valid refresh token.
    • Utilize Refresh Token Rotation: Ensure Refresh Token Rotation is enabled and that the application logic correctly handles it. This involves:
      • Always store the new refresh token returned after a successful refresh operation.
      • Discarding the old refresh token that was just used.
      • Use only the latest stored refresh token for subsequent refresh requests.

  2. Correct Custom Token Handling Logic: If refresh tokens are managed outside of a standard SDK, thoroughly review the custom logic. Ensure it correctly implements token rotation, storage, and reuse detection according to best practices to prevent using stale or invalidated tokens. Rely on standard SDKs for token management whenever feasible.

  3. Review Token Lifetime Settings: Check the Absolute Lifetime and Inactivity Lifetime configured for refresh tokens in the Auth0 dashboard (Applications > Application Settings > Addons > Token Settings or via the Management API). Ensure these lifetimes align with security requirements and application use cases. Consider whether very long lifetimes contribute to troubleshooting difficulties.

  4. Evaluate Reuse Interval (Leeway): If using Refresh Token Rotation, review the Reuse Interval setting. While a short interval can provide a buffer against immediate failures after rotation (e.g., network issues preventing the client from receiving the new token), relying heavily on it can mask underlying problems. Ensure the interval is set appropriately for the application’s needs and does not compromise security.

  5. Implement Application Error Handling: Enhance application logic to handle potential failures during the token refresh process gracefully.

    • Include retry mechanisms for transient network errors during the API call to exchange the refresh token.
    • If the 403: Unknown or invalid refresh token error is received, treat the refresh token as permanently invalid and prompt the user to re-authenticate.