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:
  • An OAuth 2.0 client is registered and authorised for your integration.
  • 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.

​
Scope

All instructions assume:
  • An OAuth 2.0 integration with Pleo APIs
  • Integration with the Staging environment

​
OAuth 2.0 Workflow Steps

​
1. Register OAuth Client

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

​
2. Direct Users to Authorisation Endpoint

Purpose:
Redirecting users to Pleo ensures they explicitly grant your integration 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:

​
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

​
4. Use Access Token to Call APIs

Purpose:
Access tokens authenticate your integration 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

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

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

​
What Comes Next?

Once Staging access is confirmed and your integration can successfully call Pleo APIs using OAuth 2.0, follow the AS/ERP Integration Quickstart to start building your Level 1-4 integration.

​
FAQs

These terms describe different parts of how OAuth 2.0 works in the Pleo platform.The difference between an integration, application, and OAuth 2.0 client is explained in the OAuth 2.0 Concepts and Terminology section.