Skip to main content
This how-to explains how to refresh OAuth 2.0 access tokens when they expire, allowing your integration to maintain continuous access to Pleo APIs without requiring users to reauthorise.

​
Overview

Access tokens issued by Pleo are short-lived.
To continue calling Pleo APIs, your integration must use the refresh token to obtain a new access token when the current one expires. Refreshing tokens:
  • Happens without user interaction
  • Must be handled server-side
  • Must be safe against race conditions and retries

​
Steps

​
1. Determine When to Refresh Tokens

Your integration should refresh the access token when:
  • The token is about to expire (preferred), or
  • An API call fails due to token expiration
Use the expires_in value returned during token exchange to track expiry.
Refreshing tokens slightly before expiry reduces the risk of failed API calls during active workflows.

​
2. Send a Refresh Token Request

To refresh tokens, make a request to Pleo’s token endpoint using the refresh token grant. The request must include:
  • grant_type: refresh_token
  • refresh_token: the current refresh token
  • client_id
  • client_secret
The request must be sent from a secure backend service over HTTPS.

​
3. Handle the Token Refresh Response

A successful refresh response returns:
  • A new access token
  • A new refresh token
  • A new expires_in value
Your integration must:
  • Replace the stored access token
  • Replace the stored refresh token
  • Update the expiry timestamp
Always persist both tokens after a successful refresh. Refresh tokens are rotated and old ones may no longer be valid.

​
4. Centralise Token Refresh Logic

Token refresh must be implemented in a single, centralised location within your integration. This ensures:
  • Consistent behaviour across all API calls
  • Easier monitoring and debugging
  • Correct handling of retries and failures
For design requirements, see Centralised Token Refresh.

​
5. Prevent Race Conditions

Multiple concurrent processes may detect token expiry at the same time. Your integration must ensure:
  • Only one refresh request is made at a time
  • Other requests wait for the refreshed token
Common approaches include:
  • Distributed locks
  • In-memory mutexes
  • Database-level locks
For design requirements, see Race Condition Prevention.

​
6. Handle Refresh Failures

Token refresh may fail due to:
  • Expired refresh token
  • Revoked access
  • Invalid client credentials
If a refresh attempt fails:
  • Do not retry indefinitely
  • Do not continue making API calls
  • Mark the token state as invalid
Your integration must require the user to reauthorise.

​
7. Log Refresh Activity

Your integration should log:
  • Refresh attempts (timestamped)
  • Success or failure outcomes
  • Failure reasons (where available)
These logs are critical for diagnosing authentication and session issues.

​
Result

After completing these steps:
  • Your integration refreshes access tokens without user involvement
  • API access continues seamlessly across token expirations
  • Token refresh behaviour is predictable, safe, and observable

​
What Comes Next?

Learn how to recover safely when refresh tokens expire or access is revoked →
this how-to is part of:
OAuth 2.0 Setup Workflow Guide (Manual Token Lifecycle)