Clear CMS Docs 2026

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.

  1. In the site admin, open Settings, then Site API keys.
  2. Press New key.
  3. Name: what will use it, like "Website build". It is for you, to tell keys apart later.
  4. Under It can, switch on what the key needs. Read is always on. The switches are explained below.
  5. Ends: Never, In 30 days, In 90 days or On a date. After that day the key stops working.
  6. Calls a day: a daily cap, or leave it empty for none. Every key is capped at 120 calls a minute anyway.
  7. Only these collections: tick the collections it may see. None ticked means every collection.
  8. 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 429 with a Retry-After: 60 header.
  • Calls a day, if you set one: over it, 429 with Retry-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

Last updated October 23, 2026