Skip to main content
Refresh tokens are long-lived credentials that allow your integration to obtain new access tokens without requiring users to reauthenticate. However, refresh tokens can expire or be revoked due to security policies, user actions, or other events. Integrations must handle these situations gracefully.

​
Detecting Expired or Revoked Refresh Tokens

  • Failed token refresh attempts typically indicate expiry or revocation.
  • The token endpoint will return an error response such as:
    • invalid_grant
    • invalid_token
  • Do not attempt to reuse the expired or revoked token.

​
Recovery Strategies

When a refresh token is no longer valid:
  1. Redirect Users to Reauthenticate
    • Start a new OAuth 2.0 authorisation flow.
    • Prompt the user to grant consent again, generating a new access and refresh token pair.
    • Preserve the user’s context if possible (e.g., use the state parameter to remember post-login destination).
  2. Fallback Mechanisms
    • Implement temporary measures to avoid broken sessions. For example:
      • Queue API requests until a new token is obtained.
      • Display a friendly message prompting the user to reconnect.
  3. Secure Cleanup
    • Immediately discard the expired or revoked refresh token.
    • Ensure no copies remain in storage or memory to prevent accidental reuse.

​
Best Practices

  • Centralise token refresh logic to reduce errors and race conditions.
  • Monitor refresh failures to detect potential security incidents.
  • Ensure users can recover with minimal friction to maintain trust and continuity.
  • Use consistent logging and error handling to aid debugging and operational monitoring.