> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pleo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Direct Users to the Authorisation Endpoint

export const WhatComesNext = ({children, href}) => <div className="mt-4">
    <a href={href} className="
        inline-flex items-center justify-center
        rounded-full
        bg-black text-white dark:bg-[#1f262b]
        px-5 py-2.5 text-sm font-medium
        no-underline border-0
        hover:bg-[#ffe6ea] dark:hover:bg-[#2b1f23]
        hover:text-black
        transition-colors
      ">
      {children} →
    </a>
  </div>;

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:

* [PKCE and Secured Patterns](/docs/current/integration-design/auth/oauth/implementing-oauth/integration-design-auth-oauth-pkce-and-secured-patterns)
* [OAuth 2.0 Client Configuration](/docs/current/integration-design/auth/oauth/getting-set-up/oauth-client-configuration)

| 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](/docs/current/integration-design/auth/oauth/getting-set-up/oauth-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`                                        |

<Tip>
  Generate a **unique `state` value** for every authorisation request to protect against CSRF attacks.
</Tip>

**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 theme={null}
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.

<Warning>
  **Your application must not bypass or interfere with this flow.**
</Warning>

## 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 theme={null}
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?

<WhatComesNext href="/docs/current/how-tos/oauth/how-to-handle-redirects-and-exchange-authorisation-code">
  Exchange the authorisation code for tokens
</WhatComesNext>

***

<div className="text-xs uppercase" style={{ fontVariant: 'small-caps' }}>
  this how-to is part of:
</div>

<div className="mt-4 flex flex-wrap gap-2">
  <a
    href="/docs/current/guides/oauth-workflow-guide"
    className="inline-flex items-center rounded-full border border-gray-300 dark:border-gray-600 
px-3 py-1 text-xs font-medium 
bg-white dark:bg-[#1f262b] text-black dark:text-white
hover:bg-gray-100 dark:hover:bg-[#2b2f33]
transition-colors"
  >
    OAuth 2.0 Setup Workflow Guide (Manual Token Lifecycle)
  </a>
</div>

***

## FAQs

<Accordion title="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](/docs/current/authentication/oauth/oauth-overview#concepts-and-terminology) section.
</Accordion>

***

## Related Reading

* [OAuth 2.0 Client Registration](/docs/current/integration-design/auth/oauth/getting-set-up/oauth-client-registration) – Step-by-step details of required fields, credentials, and redirect URIs.
* [OAuth 2.0 Client Configuration](/docs/current/integration-design/auth/oauth/getting-set-up/oauth-client-configuration) – How to configure your client with correct endpoints, PKCE, and authentication methods.
* [PKCE and Secured Patterns](/docs/current/integration-design/auth/oauth/implementing-oauth/integration-design-auth-oauth-pkce-and-secured-patterns) – Security requirements for public clients.

***