Skip to main content

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.

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
Always treat refresh token failures as terminal. Retrying refresh requests will not resolve revoked or expired tokens.

​
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:

​
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

​
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?

Go back to guide →
this how-to is part of:
OAuth 2.0 Setup Workflow Guide (Manual Token Lifecycle)