> ## 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.

# How to Handle Token Expiry or Revocation

export const WhatComesNext = ({children, href}) => <div className="mt-4">
    <a href={href} className="
        inline-flex items-center justify-center
        rounded-full
        bg-black text-white dark:bg-[#1f262b]
        px-5 py-2.5 text-sm font-medium
        no-underline border-0
        hover:bg-[#ffe6ea] dark:hover:bg-[#2b1f23]
        hover:text-black
        transition-colors
      ">
      {children} →
    </a>
  </div>;

This how-to explains how your integration should respond when OAuth 2.0 tokens can no longer be refreshed, ensuring users can reauthenticate cleanly and integrations fail safely.

## Overview

OAuth 2.0 access relies on **refresh tokens** to maintain long-lived access to Pleo APIs.\
In some situations, refresh tokens become **invalid** and can no longer be used to obtain new access tokens.

Common causes include:

* Refresh token expiry
* User revoking access
* Client credential rotation
* Security or policy changes

When this occurs, the integration must **stop API calls** and **restart the authorisation flow**.

## Steps

### 1. Detect Token Expiry or Revocation

Your integration may detect token expiry or revocation in the following ways.

**During token refresh:**

* The refresh token request returns an error (for example, an expired or invalid token)
* Pleo rejects the refresh request

**During API calls:**

* API requests fail with an authentication or authorisation error
* The error indicates that the access token is no longer valid and cannot be refreshed

<Tip>
  Always treat refresh token failures as terminal. Retrying refresh requests will not resolve revoked or expired tokens.
</Tip>

***

### 2. Take Immediate Action

When token expiry or revocation is detected, your integration must:

1. Stop making further API requests using the invalid token
2. Mark the connection as **unauthenticated**
3. Invalidate stored access and refresh tokens
4. Require the user to reauthenticate

At this point, the OAuth 2.0 session cannot be recovered without user involvement.

***

### 3. Restart the Authorisation Flow

To restore access, the user must complete the OAuth 2.0 flow again.

Your integration should:

* Redirect the user to Pleo’s authorisation endpoint
* Request the required scopes again
* Handle the redirect and exchange a new authorisation code
* Store the newly issued access and refresh tokens

For implementation details, see:

* [How to Direct Users to the Authorisation Endpoint](/docs/current/how-tos/oauth/how-to-direct-users-to-the-authorisation-endpoint)
* [How to Handle Redirects and Exchange Authorisation Code](/docs/current/how-tos/oauth/how-to-handle-redirects-and-exchange-authorisation-code)

***

### 4. Design the Reauthentication Experience

Reauthentication should be:

* **Explicit** — users understand that access needs to be restored
* **Non-destructive** — existing configuration remains intact
* **Predictable** — there is a clear recovery path

Avoid silently failing or repeatedly retrying invalid tokens.

***

### 5. Log and Observe Failures

Your integration should log:

* Token refresh failures
* Detection of token expiry or revocation
* Reauthentication triggers

These logs are essential for diagnosing authentication issues and supporting users effectively.

***

### 6. Align With Integration Design Requirements

This how-to describes **how** to respond when tokens expire or are revoked.

For design-level requirements, see [Handling Refresh Token Expiry or Revocation](/docs/current/integration-design/auth/oauth/token-lifecycle/integration-design-auth-oauth-refresh-token-expiry-revocation)

***

## Result

After completing these steps:

* Invalid or revoked tokens are detected reliably
* API calls stop safely when access is no longer authorised
* Users are guided through a clean reauthentication flow
* Integrations recover predictably without data loss

***

## What Comes Next?

<WhatComesNext href="/docs/current/guides/oauth-workflow-guide#6-handle-token-expiry-or-revocation">
  Go back to guide
</WhatComesNext>

***

<div className="text-xs uppercase" style={{ fontVariant: 'small-caps' }}>
  this how-to is part of:
</div>

<div className="mt-4 flex flex-wrap gap-2">
  <a
    href="/docs/current/guides/oauth-workflow-guide"
    className="inline-flex items-center rounded-full border border-gray-300 dark:border-gray-600 
px-3 py-1 text-xs font-medium 
bg-white dark:bg-[#1f262b] text-black dark:text-white
hover:bg-gray-100 dark:hover:bg-[#2b2f33]
transition-colors"
  >
    OAuth 2.0 Setup Workflow Guide (Manual Token Lifecycle)
  </a>
</div>

***

## Related Reading

* [Token Lifecycle](/docs/current/integration-design/auth/oauth/token-lifecycle/integration-design-auth-oauth-token-overview)
* [OAuth 2.0 Client Registration](/docs/current/integration-design/auth/oauth/getting-set-up/oauth-client-registration) – Step-by-step details of required fields, credentials, and redirect URIs.
* [OAuth 2.0 Client Configuration](/docs/current/integration-design/auth/oauth/getting-set-up/oauth-client-configuration) – How to configure your client with correct endpoints, PKCE, and authentication methods.
* [PKCE and Secured Patterns](/docs/current/integration-design/auth/oauth/implementing-oauth/integration-design-auth-oauth-pkce-and-secured-patterns) – Security requirements for public clients.

***