Skip to main content
In OAuth 2.0, access tokens and refresh tokens are used to securely access protected Pleo APIs without exposing user credentials. This page explains what tokens are, how they behave, and the rules integrations must follow when using them. It does not describe implementation details, which are covered in the linked lifecycle guides. Both access tokens and refresh tokens must be treated as opaque values. Integrations must not inspect, decode, or rely on token structure, contents, or format.

​
Access Tokens

Access tokens allow your application to call Pleo APIs on behalf of an authorised user, within the limits of the granted scopes.
  • Issued by Pleo’s Authorisation Server
  • Sent with each request to Pleo resource servers
  • Short-lived and expire after a limited period
The access token lifetime is provided in the expires_in field of the token response.
Integrations should proactively refresh access tokens before they expire to avoid failed API calls or degraded user experience.

​
Refresh Tokens

Refresh tokens allow your integration to obtain new access tokens without requiring the user to reauthenticate.
  • Longer-lived than access tokens
  • Lifetime is not fixed and must not be assumed
  • Valid for at least 60 days, but may expire or be revoked earlier
If an expired refresh token is used, all active refresh tokens for that authorisation are invalidated to prevent replay attacks.

​
Token Opacity and Safety

Access tokens and refresh tokens are opaque strings issued by Pleo.
Do not parse, decode, or infer meaning from token values. Their format is not guaranteed and may change without notice.
Your integration must store tokens securely and present them back to Pleo APIs exactly as received.

​
Token Replacement Rules

When refreshing tokens:
  • A new access token and new refresh token are issued
  • All previous access and refresh tokens must be discarded immediately
  • Reusing old tokens may result in authentication failures or revoked sessions
Integrations must always persist and use only the latest token pair.

​
Common Token Scenarios

​
Access Token Expired

  • Use the refresh token to obtain a new access token
  • Do not prompt the user unless refresh fails

​
Refresh Token Expired or Revoked

  • Restart the OAuth 2.0 authorisation flow
  • Prompt the user to reauthenticate and grant consent again