How to Direct Users to the Authorisation Endpoint

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:

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.

Optional Pleo-specific parameter

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

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

What is the difference between an integration, application, and OAuth 2.0 client?

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.

OAuth 2.0 Client Registration – Step-by-step details of required fields, credentials, and redirect URIs.
OAuth 2.0 Client Configuration – How to configure your client with correct endpoints, PKCE, and authentication methods.
PKCE and Secured Patterns – Security requirements for public clients.

Get Started

Authentication and Authorisation

Platform Capabilities & Concepts

Integration Design

Workflow Guides

How-to's

GLOSSARY

ARCHIVED

How to Direct Users to the Authorisation Endpoint

Prerequisites

Steps

1. Decide When to Redirect Users

2. Prepare PKCE Values

3. Build the Authorisation Request

Example Redirect

5. Receive the Redirect Response

Example Redirect Response

Result

What Comes Next?

FAQs

​Prerequisites

​Steps

​1. Decide When to Redirect Users

​2. Prepare PKCE Values

​3. Build the Authorisation Request

​Example Redirect

​4. Handle the User Consent Flow

​5. Receive the Redirect Response

​Example Redirect Response

​Result

​What Comes Next?

​FAQs

​Related Reading

Prerequisites

Steps

1. Decide When to Redirect Users

2. Prepare PKCE Values

3. Build the Authorisation Request

Example Redirect

4. Handle the User Consent Flow

5. Receive the Redirect Response

Example Redirect Response

Result

What Comes Next?

FAQs

Related Reading