Cleo Pay API Authentication: Bearer Token Setup and Usage

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

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:

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.

{
  "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.

{
  "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

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.

Next steps

Follow the Quickstart to make your first authenticated API call end to end.
Read about Payments to understand what you can do once you’re authenticated.

Get Started

Core Concepts

How-To Guides

Reference

Cleo Pay API Authentication: Bearer Token Setup and Usage

Sending the Authorization header

curl example

Request with a JSON body

Token format

Error responses

401 Unauthorized

403 Forbidden

Security best practices

Next steps

​Sending the Authorization header

​curl example

​Request with a JSON body

​Token format

​Error responses

​401 Unauthorized

​403 Forbidden

​Security best practices

​Next steps

Sending the Authorization header

curl example

Request with a JSON body

Token format

Error responses

401 Unauthorized

403 Forbidden

Security best practices

Next steps