Skip to main content
This workflow outlines how third-party applications integrate securely with Pleo using OAuth 2.0. Each step explains what happens, why it matters, and the expected result, while linking to detailed how-to guides for implementation. By following this guide, developers and architects can understand how the pieces fit together, ensuring a secure and reliable integration.

​
What You’ll Have Built

After completing the workflow:
  • Your application is registered and authorised with Pleo.
  • Access and refresh tokens are obtained, stored securely, and refreshed correctly.
  • Your integration can interact with Pleo APIs safely, respecting scopes and user consent.
  • The OAuth flow is resilient to token expiry, revocation, and race conditions.

​
Who This Guide Is For

This guide is intended for developers and architects implementing OAuth 2.0 integrations with Pleo APIs. It focuses on workflow understanding, not step-by-step coding details, those are in the linked how-to guides.

​
Versioning

All instructions assume OAuth 2.0 integration with Pleo APIs.

​
OAuth Workflow Steps

​
1. Register OAuth Client

Purpose:
Registering your application with Pleo ensures it can request access to user resources securely. This step provides the credentials and configuration needed to start the OAuth flow. Input:
  • Information about your app: name, URI, logo, terms, privacy policy
  • Redirect URIs and scope requirements
Output:
  • A Client ID and Client Secret
  • Defined redirect URIs registered with Pleo
  • Your application ready for user authorisation
Integration Design / Why It Matters:

How to Register an OAuth 2.0 Client

Complete client registration and configure credentials for your app.

→

​
2. Direct Users to Authorisation Endpoint

If you’re testing in our Staging environment using Postman, then you’ll skip steps 2 - 6 in this guide as Postman will handle the redirects and issuance of Access Tokens.
Purpose:
Redirecting users to Pleo ensures they explicitly grant your app permission to access their data. This step is required before any tokens are issued. Input:
  • The Client ID from the previous step
  • PKCE values (code_verifier / code_challenge)
Output:
  • Users see the Pleo consent screen and approve or deny access
  • An authorisation code is issued upon approval
Integration Design / Why It Matters:

How to Direct Users to the Authorisation Endpoint

Send users to Pleo for secure consent and obtain an authorisation code.

→

​
3. Handle Redirect & Exchange Authorisation Code

Purpose:
Exchange the short-lived authorisation code for access and refresh tokens securely. This step moves credentials from user consent to usable tokens for API access. Input:
  • Authorisation code returned from Pleo
  • Stored code_verifier (for PKCE)
Output:
  • Access and refresh tokens issued and stored securely on your backend
Integration Design / Why It Matters:
  • Token exchange must be server-to-server to keep secrets safe
  • PKCE verification ensures the code wasn’t intercepted
  • See: PKCE and Secured Patterns

How to Handle Redirects & Exchange Authorisation Code

Exchange the authorisation code for access and refresh tokens securely.

→

​
4. Use Access Token to Call APIs

Purpose:
Access tokens authenticate your app when interacting with Pleo APIs, eliminating the need for user credentials on each request. Input:
  • Access token obtained in the previous step
Output:
  • API endpoints respond with requested data or action confirmation (JSON payloads, status codes)
Integration Design / Why It Matters:
  • Always send tokens in the Authorization header over HTTPS
  • Ensure required scopes match endpoint permissions
  • Token misuse or exposure could compromise security
  • See: Token Lifecycle Overview

How to Call Pleo APIs Using Access Token

Authenticate requests and interact with Pleo APIs using the access token.

→

​
5. Refresh Tokens Centrally

Purpose:
Access tokens expire quickly. Using refresh tokens allows your integration to maintain access without requiring user intervention. Input:
  • Stored refresh token from the previous step
  • Client credentials
Output:
  • New access and refresh tokens
  • Updated expiry timestamps
Integration Design / Why It Matters:

How to Refresh Tokens

Maintain access by refreshing tokens safely and securely.

→

​
6. Handle Token Expiry or Revocation

Purpose:
Refresh tokens can expire or be revoked. Detecting and handling these events ensures your integration fails safely and can guide users to reauthenticate. Input:
  • API errors or failed refresh attempts indicating invalid or revoked tokens
Output:
  • Integration stops API calls using invalid tokens
  • Users are prompted to reauthenticate
  • Newly issued tokens replace invalid ones
Integration Design / Why It Matters:

How to Handle Token Expiry or Revocation

Recover safely when refresh tokens expire or access is revoked.

→

​
What Comes Next?

Once Staging access is confirmed and your partner integration can successfully call Pleo APIs using OAuth 2.0, you can continue with:
  • Export Expenses Workflow Guide (coming soon)