API keys

Draft. This page describes keys as implemented. The production host names are not live yet.

Scopes

A key has exactly one scope. Scopes are not a ladder: each lists what it can do.

Scope	Key looks like	Can
submit	cf_live_...	Post leads from a website. Nothing else.
read	cf_live_...	Read forms, submissions and snippets.
read_create	cf_agent_...	Everything in read, create draft forms, send a test lead, and ask for changes that wait for approval.

The MCP endpoint needs a key that can read. A submit-only key is refused with 403 scope_missing before any tool runs.

Create, see and revoke

A site owner creates keys under Settings, API keys, or from the Agents page. The full key is shown once, in the answer that creates it; after that only a 12-character prefix is shown. Copy it then.
The Agents page lists each agent key with its label, scope, last use and state. Last use moves when an agent connects or calls anything.
Revoking takes effect on the very next request, over REST and MCP, including a client that is already connected.
A site holds at most 20 active keys. Keys are stored only as a keyed hash; nobody can read one back.
Only a site owner can create or revoke a key. An API key cannot manage keys.

An agent can also get a key without an account; that key starts weak and must be claimed by the owner. See Create a form with no account.

Keys and sites

A key belongs to one site. A form, submission or approval of another site answers the same way as one that does not exist, so ids cannot be used to probe. If the site is handed off or its account is suspended, the key stops working (writes first).

Suspension, pause and caps

Caps per key: 60 calls a minute, 1,000 a day, and 5,000 rows read a day (a call is charged for the rows it returns, at least one, so polling an empty inbox costs one row a call). Over a cap the answer is 429 rate_limited with Retry-After.
Automatic suspension: a key that is refused 25 times in 10 minutes (limits, wrong scope, unknown ids), sends 50 invalid requests in 10 minutes, or repeats the same approval request 30 times in 10 minutes is suspended. Every call then answers 403 key_suspended. Nothing is deleted: its forms, the leads, and any approvals it asked for stay, and an owner can still approve them.
Resume: the owner presses Resume on the Agents page. The counters start again. A revoked key cannot be resumed.
Pause all agents: the owner can pause every agent key of a site at once. Their calls answer 503 capability_paused until the owner resumes. Visitors' form posts do not use keys and keep working.
Each of these appears in the activity log, and suspensions and pauses are audited.