Skip to main content
Authenticate every /v1/ request with an API key, sent as a bearer token. For developers making their first call to the Cleff API.
Agents: fetch this page as plain markdown at https://docs.usecleff.com/authentication.md.

​
Get your first key

  1. Sign up at app.usecleff.com/signup.
  2. Verify the email address you signed up with.
  3. Sign in to the dashboard, fill in and submit your business profile under Settings → Company.
  4. Create a key under Settings → API keys.
Signing up creates no key. The dashboard opens API keys once the email address is verified and your business profile is submitted, and a production key only once your Business is verified; see Go live.

​
Send the key

Send the key in the Authorization header:

​
Read the key format

ck_<environment>_<id_prefix>_<secret>
  • environment: sandbox or production
  • id_prefix: 8 hex characters, a public-safe identifier shown in the dashboard
  • secret: random, and never stored in plaintext

​
Scope a key to one Business and environment

A key only sees the Business and the environment (sandbox or production) it was created for. Anything outside that scope returns 404, not 403. If an ID you know exists comes back 404, check the key’s environment.

​
Store and rotate a key

The key is shown exactly once, when you create it. Store it then: Cleff keeps only a verifier and cannot show it to you again.
If a key leaks or you lose it, rotate it from the dashboard.
Rotation issues a new key and revokes the old one immediately: requests still sending the old key start failing at once. Rotate a key a live integration uses only when you can deploy the new key straight away.

​
Next steps

Idempotency

Retry a request safely after a timeout or a 5xx.

Errors

What each error code means and how to fix it.

Webhooks

Receive signed payout and beneficiary events instead of polling.