Authentication
Create a key in Cleo and authenticate requests with a bearer token.
Content reviewed · Maintained by Cleo Powered · Report a documentation issue · Verification basis
Verify your US phone before using the API. Muse and other execution-capable bots can register your account and obtain a key with your consent. You can also sign up in Cleo and create a key in Settings. Every call still requires your authorization. Learn about API access.
Create a key
- Sign in to Cleo Settings → API.
- Choose New API key, enter a name and expiration, then select Create. Complete assistant setup first if key creation is unavailable.
- Copy the full key immediately. Store it in your server’s secret manager or enter it at a hidden local prompt.
A key looks like nd_sk_<public-id>_<secret>. A platform login session is a different credential and cannot replace this API key.
Authenticate every call request
Authorization: Bearer <API_KEY>Make requests from your server or a local script. Keep the key out of frontend JavaScript, source control, URLs, and logs. The examples read CLEO_API_KEY from your environment or use a hidden prompt.
Set a descriptive User-Agent, such as CleoDocs/1.0. Python’s default client signature may be rejected by the site’s traffic filter.
- Value
CLEO_API_KEY- Where it comes from
- A secret credential created in Settings, sent in Authorization.
- When to reuse it
- Across calls until it expires or is revoked.
- Value
IDEMPOTENCY_KEY- Where it comes from
- An identifier you generate before creation, sent in Idempotency-Key.
- When to reuse it
- Only for retries of the same intended call with the same payload.
- Value
CALL_ID- Where it comes from
- The id returned by the create response.
- When to reuse it
- To get, sync, or cancel that existing call.
| Value | Where it comes from | When to reuse it |
|---|---|---|
CLEO_API_KEY | A secret credential created in Settings, sent in Authorization. | Across calls until it expires or is revoked. |
IDEMPOTENCY_KEY | An identifier you generate before creation, sent in Idempotency-Key. | Only for retries of the same intended call with the same payload. |
CALL_ID | The id returned by the create response. | To get, sync, or cancel that existing call. |
These values are not interchangeable. Health checks require none of them.
Workspace and key ownership
Each key belongs to an Agent Project: the group that ties keys to your workspace assistant and its API calls. Cleo creates this group automatically when saving your first task or completing assistant setup; you do not need to create a project manually.
- Keys from the same project share access to its calls and idempotency history.
- A key from another project cannot read or cancel those calls.
- API-created tasks and calls are visible in the owning workspace’s platform history.
Rotate a key
- Create a replacement key.
- Update your application to use it and verify a request.
- Revoke the old key in Settings.
Revoking the original key can prevent its queued work from being dispatched. It does not itself cancel a call already in progress. Keep a working key from the same project to read, sync, or cancel them.
Revoked and expired keys return 401. Key validation happens on each API operation, so revoking a key prevents subsequent requests with it.