Follow these steps to redirect users to Pleo’s OAuth 2.0 authorisation endpoint so they can grant your application permission to access their Pleo data.
Redirecting users is required before any access tokens can be issued. At this stage, your application does not authenticate users or make API calls.
Prerequisites
Before you begin:
- Your application is registered as an OAuth 2.0 client with Pleo.
- You have a Client ID.
- You have at least one registered redirect URI.
- You do not yet have access tokens.
Steps
1. Decide When to Redirect Users
Redirect users when:
- They select a Connect to Pleo action in your application.
- Their previous authorisation has expired or been revoked.
- A refresh token can no longer be used.
This ensures users explicitly control access to their data.
2. Prepare PKCE Values
Pleo requires PKCE (Proof Key for Code Exchange) by default.
Before redirecting the user:
- Generate a cryptographically random code verifier.
- Derive a code challenge using SHA-256.
- Store the code verifier securely on your server or in the user session.
The code verifier is required later when exchanging the authorisation code for tokens.
For full PKCE and client configuration details, including supported authentication methods and server URLs, see:
| Parameter | Description | Example |
|---|
code_verifier (not sent) | Random value used once per authorisation request. Stored securely until the token exchange. | ab1C_DefG2gA3_bcdefGhAbCD-efGha45cdEFGHaB6C |
code_challenge | SHA-256–derived value sent to the authorisation endpoint | aB1C23D4EFgH-5I6JK7lMnOpQRs8T9OuvW12_Xy3zAB |
3. Build the Authorisation Request
Redirect the user’s browser to Pleo’s OAuth 2.0 authorisation endpoint using an HTTP redirect.
The request must include the following parameters (refer to Client Configuration for server URLs and authentication method details):
| Parameter | Description | Example |
|---|
response_type | Must be set to code | code |
client_id | OAuth 2.0 Client ID issued by Pleo | 12a3b456-78c9-0d12-93f4-f567ab8cde9f |
redirect_uri | One of your registered redirect URIs | https://client.example/callback |
scope | Space-separated list of requested API scopes | test:test users:read |
state | Opaque value used to protect request integrity | a1b2c3456d78e90fab1c23456d78ef |
code_challenge | PKCE challenge derived from the code verifier | aB1C23D4EFgH-5I6JK7lMnOpQRs8T9OuvW12_Xy3zAB |
code_challenge_method | Must be S256 | S256 |
Generate a unique state value for every authorisation request to protect against CSRF attacks.
| Parameter | Description | Example |
|---|
urn_pleo_params_oauth_subject | Subject URN returned during session handover | urn:pleo:company:123a4567-b89c-12d3-e456-789012345678 |
Example Redirect
HTTP/1.1 302 Found
Location: https://auth.pleo.io/oauth/authorize
?response_type=code
&client_id=12a3b456-78c9-0d12-93f4-f567ab8cde9f
&redirect_uri=https%3A%2F%2Fclient.example%2Fcallback
&scope=test%3Atest+users%3Aread
&state=a1b2c3456d78e90fab1c23456d78ef
&code_challenge=aB1C23D4EFgH-5I6JK7lMnOpQRs8T9OuvW12_Xy3zAB
&code_challenge_method=S256
4. Handle the User Consent Flow
After the redirect:
- Pleo authenticates the user (if required).
- Pleo displays a consent screen showing:
- Your application name and logo
- The requested scopes
- The user approves or denies access.
Your application must not bypass or interfere with this flow.
5. Receive the Redirect Response
If the user approves access:
- Pleo redirects the browser back to your
redirect_uri.
- An authorisation code is included in the query parameters.
- The original
state value is returned unchanged.
If the user denies access:
- The redirect contains an error.
- No authorisation code is issued.
Example Redirect Response
HTTP/1.1 302 Found
Location: https://client.example/callback
?code=Abcde1FgHIJKlMN2OpQrST
&state=a1b2c3456d78e90fab1c23456d78ef
Result
After completing these steps:
- The user has authenticated with Pleo.
- The user has granted or denied consent.
- Your application has received an authorisation code if the user granted consent.
- No access tokens exist yet.
- API calls are not possible at this stage.
What Comes Next?
You now need to exchange the authorisation code for access and refresh tokens.
