> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pleo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling Refresh Token Expiry or Revocation

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](/docs/current/integration-design/auth/oauth/token-lifecycle/integration-design-auth-oauth-centralised-token-refresh) 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.

## Related Reading

* **[OAuth 2.0 Overview](/docs/current/integration-design/auth/oauth/integration-design-auth-oauth-overview)** - introduction to OAuth 2.0 for Pleo integrations
* **[API Keys Overview](/docs/current/authentication/standalone-api-keys-overview)** – alternative authentication method
* **[Tokens Overview](/docs/current/integration-design/auth/oauth/token-lifecycle/integration-design-auth-oauth-token-overview)** – understanding access and refresh tokens
* **[Secure Token Storage](/docs/current/integration-design/auth/oauth/token-lifecycle/integration-design-auth-oauth-secure-token-storage)** – storing credentials securely
* **[Race Condition Prevention](/docs/current/integration-design/auth/oauth/token-lifecycle/integration-design-auth-oauth-race-condition-prevention)** – avoid duplicate token refresh attempts
* **[OAuth 2.0 Setup Workflow Guide](/docs/current/guides/oauth-workflow-guide)** - Step-by-step guide to configure OAuth 2.0 for your integration