Skip to main content
This how-to explains how to handle the redirect from Pleo after user consent and how to exchange the returned authorisation code for OAuth 2.0 tokens. It assumes you are managing the redirect handling and token lifecycle on your backend. For context on why this is needed, see OAuth 2.0 Client Configuration and PKCE and Secured Patterns.

​
Prerequisites

Before you begin, ensure that:
  • You have registered an OAuth 2.0 client with Pleo
  • You have implemented the authorisation redirect flow
  • You have a backend endpoint registered as your redirect_uri
  • You are using PKCE and have stored the original code_verifier
  • You can make secure server-to-server HTTP requests

​
Steps

​
1. Understand the Redirect

After a user grants consent on Pleo’s authorisation screen, Pleo redirects the user’s browser back to your application. The redirect contains a short-lived authorisation code that must be exchanged for tokens before any API access is possible. At this stage:
  • User consent has already been granted
  • No API access is possible yet
  • Tokens must be obtained securely on the backend

​
2. Receive the Redirect

Pleo redirects the browser to your registered redirect_uri with query parameters. A successful redirect includes:
  • code — the authorisation code
  • state — the original value sent in the authorisation request
A failed redirect includes:
  • error
  • error_description (optional)
  • state
Your redirect endpoint must be able to handle both cases.

​
3. Validate the Redirect

Before exchanging the authorisation code, perform the following checks:
  • Verify the state value
    Ensure it matches the value you generated before redirecting the user.
    This protects against CSRF attacks.
  • Ensure a code is present
    If no authorisation code is returned, treat the flow as failed.
Never proceed with token exchange if the state validation fails.

​
4. Exchange the Authorisation Code for Tokens

The authorisation code must be exchanged server-to-server using Pleo’s token endpoint. This request must never be made from a frontend or client-side application.

​
5. Send the Token Exchange Request

The token exchange request must include the following parameters:
ParameterDescription
grant_typeMust be authorization_code
codeAuthorisation code received from Pleo
redirect_uriMust match the registered redirect URI
client_idYour OAuth 2.0 Client ID
client_secretYour OAuth 2.0 Client Secret
code_verifierOriginal PKCE code verifier
The code_verifier must be the exact value used to generate the code_challenge during authorisation.

​
Example Request

POST /oauth/token HTTP/1.1
Host: auth.pleo.io
Authorization: Basic AbCdE1F2GHIjKLMnOp34QRS5TUvwXyzaBCDeF6GhI7JkLmNOPqrsTuvwXyZaBcD8EfGhIJklMnOpQrStUVWxyZA9BC==
Content-Type: application/x-www-form-urlencoded

grant_type=authorisation_code
&code=Abcde1FgHIJKlMN2OpQrST
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Fcallback
&code_verifier=ab1C_DefG2gA3_bcdefGhAbCD-efGha45cdEFGHaB6C

​
6. Handle the Token Response

A successful token exchange returns:
  • access_token
  • refresh_token
  • expires_in
  • token_type
  • scope
Your backend must:
  • Store tokens securely
  • Associate tokens with the correct Pleo company or entity
  • Track token expiry time for future refresh operations
For guidance on secure storage, see Secure Token Storage.

​
7. Handle Token Exchange Errors

Token exchange can fail for several reasons:
  • Invalid or expired authorisation code
  • Mismatched redirect URI
  • Invalid client credentials
  • Incorrect or missing PKCE verifier
If the exchange fails:
  • Do not retry with the same authorisation code
  • Restart the OAuth 2.0 flow if required
  • Log failures for troubleshooting
Proper error handling ensures your integration can recover gracefully and inform users if reauthentication is needed.

​
8. Follow Authorisation Code Rules

  • Authorisation codes are single-use and expire quickly
  • Any used or expired code will be rejected by Pleo
Always treat authorisation codes as short-lived secrets and exchange them immediately upon receipt.

​
9. Store Tokens Securely

Tokens must be stored according to security best practices:
  • Store tokens only on secure backend systems
  • Never expose tokens to end users
  • Encrypt tokens at rest where possible
See Secure Token Storage for detailed guidelines and recommended patterns.

​
10. Track and Manage Token Expiry

To maintain uninterrupted access:

​
Result

After completing these steps:
  • Your backend has securely validated the OAuth 2.0 redirect
  • Your application has exchanged a single-use authorisation code for tokens
  • Access and refresh tokens are stored securely
  • Your application is now authorised to access Pleo APIs

​
What Comes Next?

How to Call Pleo APIs Using Access Tokens

Use your access token to make authenticated requests to Pleo APIs.

→