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

# Authentication and Authorisation

> To access the Subscriptions API, you can use any of the following (provided during the initial integration set up of the customer):

* JWT token (OAuth)
* API key

<Info>
  ℹ️ **Important**:

  * The **JWT token** or the **API key** is generated either for a company or an organisation owning different subsidiaries in a multi-entity set up.
  * In your subsequent subscription requests, use the same JWT token (OAuth) or the API key (provided during the initial configuration). This implies that for the subsequent requests, you receive webhook notifications for the same entity that Pleo has authorised. For example, Newday is a credit card organisation. It owns Newday Technology Limited and Newday Cards Ltd. Each JWT token or API key is generated for a specific entity (either Newday Technology Limited or Newday Cards Ltd). To receive webhook notifications for multiple entities, you need to create separate subscriptions using separate JWT tokens or API keys for each entity.
</Info>

## Authentication Methods for Webhooks Verification

Pleo supports the following:

* **HMAC Signature-Based**: We support and recommend this authentication method. To learn more, click [here](#hmac-signature-based-authentication).
* **Basic authentication**: If the integration does **not** support **HMAC signature-based** authentication, use this method as an alternative option. To learn more, click [here](#basic-authentication).
* **Header-based authentication**: If the integration does **not** support **HMAC signature-based** authentication, you can use header-based authentication as another alternative option. To learn more, click [here](#header-based-authentication).

### HMAC Signature-Based Authentication

In this authentication method, webhook-timsetamp and webhook-signature are sent in the request headers as unique parameters of the webhook notification.

```json theme={null}
{
    "webhook-id":"msg_p5jXN8AQM9LWM0D4loKWxJek",
    "webhook-timestamp":1614265330,
    "webhook-signature":"v1,g0hM9SsE+OTPJTGttmIKtSyZlE3uFJELVlNIOLJ1OE="
 }
```

### Basic Authentication

In this method of authentication, the integration can send `username` and `password` in the request header of [Create a Subscription](/reference/subscriptions/create-a-subscription) request. The credentials are also included in the webhook notification sent to the configured endpoint, enabling the consumer system to validate the authenticity of the notification using the **Basic Authentication** mechanisms.

**Endpoint**: POST /v1/subscriptions

**Request message**:

```json theme={null}
{
    "status": "ACTIVE",
    "eventTypes": ["v1.export-job.created"],
    "endpointUrl": "<https://b7baf754-64e1-4469-ba23-fd7b5988eaf7.mock.pstmn.io/webhook>",
    "endpointAuth": {
        "type": "BASIC",
        "credentials": {
            "username": "your_username",
            "password": "your_password"
        }
    },
    "customHeaders": { 
        "Content-Type": "application/json" 
    }
}
```

**Response message**:

```json theme={null}
{
    "data": {
        "id": "c21a9d0e-f31b-4302-890d-751d400bbe21",
        "status": "ACTIVE",
        "eventTypes": [
            "v1.export-job.created"
        ],
        "endpointUrl": "<https://b7baf754-64e1-4469-ba23-fd7b5988eaf7.mock.pstmn.io/webhook>",
        "createdAt": "2025-03-24T16:28:23.090589Z",
        "updatedAt": "2025-03-24T16:28:23.090589Z",
			   "endpointAuth": {
			       "type": "BASIC",
			       "credentials": {
			           "username": "your_username",
			           "password": "your_password"
			       }
			   },
			   "customHeaders": { 
			       "Content-Type": "application/json" 
			   }         
    }
}
```

### Header-based Authentication

In this method, the integration can include custom header in the request message to [Create a Subscription](/reference/subscriptions/create-a-subscription) endpoint. The headers can include API keys, bearer tokens, or any other value that the consumer system requires for authenticating the incoming webhook notification.

**Endpoint**: POST /v1/subscriptions:

**Request message**:

```json theme={null}
{
   "status":"ACTIVE",
   "eventTypes":[
      "v1.export-job.created"
   ],
   "endpointUrl":"<https://b7baf754-64e1-4469-ba23-fd7b5988eaf7.mock.pstmn.io/webhook>",
   "customHeaders":{
      "x-api-key":"xxxxx",
      "Authorization":"Bearer your_token",
      "Content-Type":"application/json",
      "User-Agent":"Chrome/129.0"
   }
}
```

**Response message**

```json theme={null}
{
   "data": {
      "id": "2bfde1d4-b3be-4135-960a-914b41ed2dcc",
      "status": "ACTIVE",
      "eventTypes": [
         "v1.export-job.created"
      ],
      "endpointUrl": "<https://b7baf754-64e1-4469-ba23-fd7b5988eaf7.mock.pstmn.io/webhook>",
      "createdAt": "2025-03-24T16:19:23.113886Z",
      "updatedAt": "2025-03-24T16:19:23.113886Z"
   },
   "endpointAuth": {
      "type": "NONE"
   },
   "customHeaders": {
      "x-api-key": "xxxxx",
      "Authorization": "Bearer your_token",
      "Content-Type": "application/json",
      "User-Agent": "Chrome/129.0"
   }
}
```

#### **Configuring Custom Headers in New Subscription Request**

While creating a new subscription request, the integration can send a custom header in the API request. For example, the integration can specify the content-type or the user-agent it wants to receive in the API response.

**Endpoint**: [Create a Subscription](/reference/subscriptions/create-a-subscription)

**Request message**:

```json theme={null}
{
    "status": "ACTIVE",
    "eventTypes": ["v1.export-job.created"],
    "endpointUrl": "<https://b7baf754-64e1-4469-ba23-fd7b5988eaf7.mock.pstmn.io/webhook>",
    "customHeaders": {
		    "Content-Type": "application/json",
		    "User-Agent": "Chrome/129.0"
		}
}
```

**Response message**:

```json theme={null}
{
   "data": {
      "id": "2bfde1d4-b3be-4135-960a-914b41ed2dcc",
      "status": "ACTIVE",
      "eventTypes": [
         "v1.export-job.created"
      ],
      "endpointUrl": "<https://b7baf754-64e1-4469-ba23-fd7b5988eaf7.mock.pstmn.io/webhook>",
      "createdAt": "2025-03-24T16:19:23.113886Z",
      "updatedAt": "2025-03-24T16:19:23.113886Z"
   },
   "endpointAuth": {
      "type": "NONE"
   },
   "customHeaders": {
      "Content-Type": "application/json",
      "User-Agent": "Chrome/129.0"
   }
}
```