> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleo-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cleo Pay API Authentication: Bearer Token Setup and Usage

> Add a Bearer token to every Cleo Pay API request to authenticate. Learn the header format, error codes, and token security best practices.

Every request to the Cleo Pay API must include a valid Bearer token in the `Authorization` header. Requests without a token, or with an expired or malformed token, are rejected before they reach any endpoint. Tokens are JSON Web Tokens (JWTs) issued by Cleo Pay — they encode your identity and permissions and are verified server-side on every call.

## Sending the Authorization header

Add the following header to every API request:

```
Authorization: Bearer <your_token>
```

Replace `<your_token>` with the JWT you received from Cleo Pay.

### curl example

```bash theme={null}
curl --request GET \
  --url https://api.cleo-pay.com/v1/payables \
  --header "Authorization: Bearer <your_token>"
```

### Request with a JSON body

When sending a request body (e.g. creating a payment), include `Content-Type: application/json` alongside the `Authorization` header:

```bash theme={null}
curl --request POST \
  --url https://api.cleo-pay.com/v1/payments \
  --header "Authorization: Bearer <your_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "contactId": "c_01hq2k5r8e4vwxyz",
    "amountCents": 50000,
    "bankAccountId": "ba_01hq2k5r8e4vabc"
  }'
```

## Token format

Cleo Pay tokens are **JWTs (JSON Web Tokens)**, a standard format consisting of three Base64URL-encoded segments separated by dots: `header.payload.signature`. The payload contains your tenant identity and permission scopes. You do not need to parse the token yourself — simply forward it in the header as-is.

Tokens have an expiration time encoded in their payload (`exp` claim). If your token expires, requests will return a `401 Unauthorized` error. Obtain a fresh token and retry.

## Error responses

### 401 Unauthorized

Returned when the token is missing, malformed, or expired.

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```

**Resolution:** Check that you're including the `Authorization: Bearer <token>` header and that your token has not expired.

### 403 Forbidden

Returned when the token is valid and authenticated, but does not have permission to perform the requested action.

```json theme={null}
{
  "statusCode": 403,
  "message": "Forbidden"
}
```

**Resolution:** Confirm that your token has the required scopes or roles for the operation. Contact Cleo Pay support if you believe this is a permissions misconfiguration.

## Security best practices

<Warning>
  **Never expose your API token in client-side code, browser JavaScript, mobile apps, or application logs.** Treat your Bearer token with the same care as a password. Anyone who obtains your token can make authenticated API calls on your behalf until it expires.

  * Store tokens in environment variables or a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault).
  * Rotate tokens regularly and immediately if you suspect a compromise.
  * Strip `Authorization` headers from any logs, traces, or error reports before storing or sharing them.
</Warning>

## Next steps

* Follow the [Quickstart](/quickstart) to make your first authenticated API call end to end.
* Read about [Payments](/concepts/payments) to understand what you can do once you're authenticated.