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.

Integrations must implement a centralised mechanism to refresh access tokens using the refresh token. Refreshing tokens from multiple locations or concurrent requests can result in token invalidation, race conditions, and failed API calls.

​
Why Centralised Token Refresh Is Required

When a refresh token is used:
  • Pleo issues a new access token and a new refresh token
  • All previous tokens are immediately invalidated
If multiple parts of your system attempt to refresh tokens independently, one refresh may invalidate tokens still in use elsewhere. A single refresh authority ensures token consistency across your integration.

​
Core Requirements

Your token refresh mechanism must:
  • Monitor the expires_in field returned with access tokens
  • Refresh tokens before access tokens expire
  • Ensure only one refresh request is in flight at a time
  • Update and persist both the access token and refresh token on success
  • Immediately discard all previously issued tokens

​
Retry and Failure Handling

  • Retry refresh requests using exponential backoff for transient failures
    (for example: network timeouts or temporary service unavailability)
  • Do not retry indefinitely
  • If refresh fails due to an invalid or expired refresh token:
    • Stop retrying
    • Restart the OAuth 2.0 flow
    • Prompt the user to reauthenticate

​
Concurrency and Race Condition Prevention

To prevent multiple refresh attempts:
  • Use locking, queuing, or a shared refresh promise/future
  • Ensure all API requests depend on the same refreshed token result
  • Block or delay outgoing API calls while a refresh is in progress

​
Outcome

  • Tokens remain consistent across your system
  • Refresh token invalidation errors are avoided
  • Users are only prompted to reauthenticate when strictly necessary