Keys and authentication
How keys act as you, what limits them, and how they expire, rotate and stop.
A key is yours
A key belongs to one person and is made in their registered organization. It acts as that person, with exactly their access: the deals they are on, as what they are on them. A key never reaches further than its owner. When you lose access to a deal, so does your key.
Send it on every call:
Authorization: Bearer ck_…Keys open /api/v1 and nothing else. The Cerclen app itself doesn't accept them.
Limits you choose
- Read only or read and write. A read-only key can call any
GETand ask for download links; anything else is refused with403 read_only_key. - Deals. A key can be limited to chosen deals. Every other deal answers
404, as if it didn't exist.
A person holds at most 25 live keys.
Expiry, rotation and revocation
- Keys expire after 30, 90 or 365 days, as chosen when the key was made. A week before, Cerclen emails the owner.
- Rotate a key on the API Keys page to get a new one with the same name, access, deals and lifetime. The old key keeps working for seven days, marked Replaced, while you switch.
- Revoke a key there and it stops at once. Your organization's admins see every key on the team and can revoke any of them; they can't make or rotate one for you.
- Leaving the team revokes all of a person's keys in it.
Last used on the API Keys page shows when a key last made a call (updated at most once a minute), which helps find keys nobody uses any more.
What your key's calls look like to others
Everything a key posts appears under its owner's name, marked via API for everyone who sees it, both sides of the deal. Cerclen's audit log records which key made each change.
When a key is refused
| Status | params.reason | Meaning |
|---|---|---|
| 401 | no_api_key | No Authorization: Bearer header |
| 401 | not_an_api_key | The token isn't a Cerclen key (it doesn't start with ck_) |
| 401 | invalid_api_key | Unknown, expired or revoked, or its owner has left the organization |
| 401 | api_key_is_for_v1 | A key sent to the app's own routes rather than /api/v1 |
| 403 | read_only_key | A read-only key tried to change something |