Skip to main content
The Cleo Pay API authenticates requests using Bearer tokens. You must include a valid token in the Authorization header of every API request.

​
How to authenticate

Add the Authorization header to your requests: 
Authorization: Bearer <your-token>

curl https://api.cleo-pay.com/api/businesses \
  -H "Authorization: Bearer <your-token>"

​
Getting a token

Tokens are issued when you sign in to Cleo Pay. Once authenticated, you can retrieve a session token from the Cleo Pay application context to use in API requests. For automated or server-to-server use, generate a long-lived token from your Cleo Pay account settings.
Treat tokens like passwords. Never log them, commit them to source control, or expose them in client-side code that could be accessed by others. Rotate tokens immediately if you suspect they have been compromised.

​
Token expiry

Session tokens are short-lived. When a token expires, the API returns 401 Unauthorized. To continue making requests, sign in again to get a fresh token. Your application should handle 401 responses by refreshing the token and retrying the request.

​
Error responses

StatusMeaning
401 UnauthorizedThe token is missing, malformed, or expired. Re-authenticate to get a new token.
403 ForbiddenThe token is valid but the authenticated user does not have permission to access the requested resource. Check that your account has the necessary role.

​
Example: authenticated request

curl https://api.cleo-pay.com/api/businesses \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
Response
[
  {
    "id": "biz_01abc123",
    "name": "Acme Corp",
    "status": "verified"
  }
]

​
Next steps