API keys
A key lets a program, a script or an AI assistant work on your site. Which kind to make, what each switch means, and where to make it.
On this page
An API key is a long password for a program, not a person. You give it to your own code, a build script or an AI assistant, and that program can then read your site and save drafts, within the limits you set when you make the key.
The kinds of key
| Kind | Starts with | Reaches | Can it publish? | Made in |
|---|---|---|---|---|
| Site key | clr_site_ |
One site | Yes, if its Publish switch is on. Only an editor, admin or owner can make such a key | The site admin: Settings → Site API keys |
| Personal key | clr_user_ |
The sites you can open, never with more than your role on each | Yes, if your role may | Made for an assistant when you connect it as you (Account → AI assistants in the Console). Keys to make by hand for your personal sites are coming; keys made earlier still work |
| Organization key | clr_org_ |
The organization's sites you pick, never with more than your role on each | Yes, if its Publish switch is on | The Console: Organization → API keys. Only the organization's owners make and see them |
For most uses, make a site key. It reaches one site and does only what you switch on. For an AI assistant, Settings → AI assistants → Connect makes one for you: see API keys for assistants.
Test keys start with clr_test_ and reach only sandbox sites, whose id ends in -sandbox. A sandbox site's keys are always test keys. A live key never reaches a sandbox, and a test key never reaches a live site.
Make a site key
You need the Admin or Owner role on the site.
- In the site admin, open Settings, then Site API keys.
- Press New key.
- Name: what will use it, like "Website build". It is for you, to tell keys apart later.
- Under It can, switch on what the key needs. Read is always on. The switches are explained below.
- Ends: Never, In 30 days, In 90 days or On a date. After that day the key stops working.
- Calls a day: a daily cap, or leave it empty for none. Every key is capped at 120 calls a minute anyway.
- Only these collections: tick the collections it may see. None ticked means every collection.
- Press Make key, then copy the key now. It is shown only this once. Clear keeps a scrambled copy (a hash) and a hint, the first and last few characters, so you can tell keys apart in the list.
What each switch means
| Switch | What it allows | Name in access |
|---|---|---|
| Read | Read published content. Always on. | read |
| Save drafts | Change words and fields in records and pages. Nothing goes live. Also read drafts and make preview links. | writeDrafts |
| Pages and blocks | Make pages and collections; add, remove and move blocks; rename records and page addresses. | structure |
| Files | Upload files and move them to the trash. | media |
| Delete | Delete records and pages. Undoable until someone publishes. | delete |
| Publish | Put drafts live, and save straight to the site in a collection that goes live right away. Off until you switch it on; a key with it can change your site without anyone looking first. | publish |
| Form answers | Read what people sent through forms. This is personal data, so it is off until you switch it on. | formAnswers |
| Send email | Send the site's emails to any address, such as the thank-you to someone who filled in a form. Without it, a key that may save drafts emails only the site's own addresses, and a key that only reads sends no email at all. Site keys only. | sendEmail |
access is the list a program gets back when it asks about the site (GET …/api/v1/<site>, or the MCP tool describe_site): each switch as true or false, plus the key's limits (collections, expiresAt, callsPerDay, callsPerMinute). A well-behaved program reads it before it writes.
Personal and organization keys follow your role
A personal or organization key is never more than the person who made it. Their role on each site caps what the key may do there, whatever the switches say:
- Viewer: reads.
- Contributor: also saves drafts and uploads files.
- Editor, Designer, Admin and Owner: everything, including pages and blocks, delete and publish.
Lose your access to a site, and your keys stop working there too.
Limits
- 120 calls a minute per key, reads and writes together. Each MCP tool call counts as one. Over it, the answer is
429with aRetry-After: 60header. - Calls a day, if you set one: over it,
429withRetry-After: 3600. - Ends: after the last day, every call answers
401. Make a new key. - Only these collections: the key sees those collections only. Others answer
403.
Revoke a key
Press Revoke next to the key, on the same page where it was made. Anything using it stops at once. Revoke a key the moment you think someone else has seen it, and make a new one.
Keep keys safe
Keys have a fixed shape, so a secret scanner (GitHub push protection, gitleaks, trufflehog) can catch one that slips into code. The pattern is clr_(test_)?(site|user|org)_[0-9A-Za-z]{36}. The last six characters are a checksum, so a mistyped key is refused straight away.
Next
- The API: use a key from your own code.
- API keys for assistants: the short version for an AI assistant.
- What the tools do: what an assistant can do with a key.
- Connect your assistant: the steps for Claude Code and other tools.