Skip to main content
Follow these steps to redirect users to Pleo’s OAuth 2.0 authorisation endpoint so they can grant your OAuth 2.0 client permission to access their Pleo data. Redirecting users is required before any access tokens can be issued. At this stage, your integration does not authenticate users or make API calls.

​
Prerequisites

Before you begin:
  • Your OAuth 2.0 client is registered 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:
  1. Generate a cryptographically random code verifier.
  2. Derive a code challenge using SHA-256.
  3. 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:
ParameterDescriptionExample
code_verifier (not sent)Random value used once per authorisation request. Stored securely until the token exchange.ab1C_DefG2gA3_bcdefGhAbCD-efGha45cdEFGHaB6C
code_challengeSHA-256–derived value sent to the authorisation endpointaB1C23D4EFgH-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):
ParameterDescriptionExample
response_typeMust be set to codecode
client_idOAuth 2.0 Client ID issued by Pleo12a3b456-78c9-0d12-93f4-f567ab8cde9f
redirect_uriOne of your registered redirect URIshttps://client.example/callback
scopeSpace-separated list of requested API scopestest:test users:read
stateOpaque value used to protect request integritya1b2c3456d78e90fab1c23456d78ef
code_challengePKCE challenge derived from the code verifieraB1C23D4EFgH-5I6JK7lMnOpQRs8T9OuvW12_Xy3zAB
code_challenge_methodMust be S256S256
Generate a unique state value for every authorisation request to protect against CSRF attacks.
Optional Pleo-specific parameter
ParameterDescriptionExample
urn_pleo_params_oauth_subjectSubject URN returned during session handoverurn: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
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 registered OAuth 2.0 client 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?

Exchange the authorisation code for tokens →
this how-to is part of:
OAuth 2.0 Setup Workflow Guide (Manual Token Lifecycle)

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