Skip to main content
This how-to explains how to authenticate requests to Pleo APIs using an OAuth 2.0 access token obtained during the authorisation flow.

​
Overview

Once your application has exchanged an authorisation code for tokens, the access token is used to authenticate requests to Pleo APIs. At this stage:
  • User consent has already been granted
  • Tokens are stored securely on your backend
  • Your integration can begin interacting with Pleo resources

​
Prerequisites

Before you begin:
  • You have completed the OAuth 2.0 authorisation flow
  • You have successfully exchanged an authorisation code for tokens
  • You have a valid, unexpired access token stored securely

​
Steps

​
1. Include the Access Token in API Requests

All authenticated requests to Pleo APIs must include the access token in the Authorization header.

​
Required Header

Authorization: Bearer <access_token>
  • The token must be prefixed with Bearer
  • The header must be included on every request to protected endpoints
Never include access tokens in query parameters or request bodies.

​
2. Ensure Required Scopes Are Granted

Access tokens are issued with one or more scopes, which define what your integration is allowed to do. Before making an API call:
  • Confirm the required scope was requested during authorisation
  • Ensure the endpoint you are calling is covered by that scope
Requests made outside the granted scopes are rejected.

​
3. Make API Requests Over HTTPS

Access tokens can be used to:
  • Fetch data from Pleo (for example, expenses or export jobs)
  • Create or update resources
  • Trigger workflows such as exports
All requests must be made over HTTPS.
Use a centralised API client in your application to ensure consistent authentication, logging, and error handling.

​
4. Handle Authentication Errors

API requests may fail due to authentication-related issues. Common causes include:
  • Expired access token
  • Invalid or revoked token
  • Insufficient scopes
When an authentication error occurs:
  • Do not retry the same request blindly
  • Determine whether the token needs refreshing
  • Restart the authorisation flow if required

​
5. Track Access Token Expiry

Access tokens are short-lived. Your integration must:
  • Track the token expiry time (expires_in)
  • Refresh the token before or immediately after it expires
  • Avoid making API calls with expired tokens
For refresh strategies and race-condition handling, see Centralised Token Refresh

​
6. Follow Security Best Practices

  • Never expose access tokens to frontend clients
  • Store tokens only on secure backend systems
  • Encrypt tokens at rest where possible
  • Log authentication failures with sufficient context for troubleshooting
  • Avoid hardcoding tokens or scopes

​
Result

After completing these steps:
  • Your application can authenticate requests using a valid access token
  • API calls are authorised according to the granted scopes
  • Authentication failures are handled safely and predictably

​
What Comes Next?

How to Refresh Tokens

Learn how to refresh access tokens securely and handle expiry.

→