API keys
An API key authenticates an MCP client as you, against a single Connection — a (Project, Corpus) pair that decides exactly which corpus the agent will see. Use one when the client can’t do the OAuth sign-in flow — scripts, CI jobs, agents without a browser. For Claude Code and Claude Desktop, prefer OAuth.
A Connection is administered by an organization owner: members can read through an existing credential, but only owners can mint a new one or change what a key may do.
Creating a key
Section titled “Creating a key”API keys live on each Corpus’s Connect page, not on a top-level “API keys” screen.
- Open the Corpus you want the agent to read.
- Click Connect this corpus in the header.
- On the MCP setup page, scroll to API keys and click
+ API key. Give it a Name that says where it’s used
(
ci-release-bot,laptop-cursor). - Choose its Access (see Grants).
- Click Generate key.
The full secret is shown exactly once, on the confirmation screen.
Copy it now — this is the only time the full key is shown.
Store it in your secret manager or the client’s credential store. Corpus
keeps only a short prefix (cck_xxxxxxxx) so you can recognize the key
later; it cannot show or reset the secret. Lose it and you revoke and
create a new one.
Grants
Section titled “Grants”Every key has a grant, the same read < suggest < edit rule a
share link carries. It applies to the REST API and the
CLI; each grant includes everything before it.
| Grant | The key can |
|---|---|
read |
List and fetch the corpus’s documents. |
suggest |
Also send changes. They become proposals a person reviews hunk by hunk; nothing changes until then. |
edit |
Also write documents directly, create them, move them and archive them, with no review. |
A change with too low a grant is refused with a 403 that says what the key
may do instead. Removing or moving a document cannot be proposed, so a
suggest key cannot do either.
Pick the weakest grant the job needs: a CI job that only syncs a repository
from Corpus needs read; one that sends repository edits back for review needs
suggest. Keys minted before grants existed keep working as edit. An owner
can change a key’s grant from the Access control on the key list; it takes
effect on the key’s next request. The grant does not change what MCP
allows: over MCP a key can still only file proposals.
Using a key
Section titled “Using a key”Pass it as a bearer token on the MCP endpoint. The same Connect page generates the exact per-client snippet; the header is always:
Authorization: Bearer <YOUR_API_KEY>The token starts with cck_ so the MCP transport can tell it apart from
an OAuth JWT before doing any database work.
The same key also authenticates the CLI, which can edit the bound corpus’s documents from a terminal or CI — list, pull, and push markdown without a browser.
Revoking a key
Section titled “Revoking a key”On the Connection’s API keys list, click Revoke on the row and confirm. Agents using that key lose access immediately. Revoke a key the moment it might be exposed (a leaked CI log, a former teammate’s laptop) and issue a fresh one — keys are cheap, name them per use so you can revoke narrowly.
Deleting the whole Connection (Settings → Connections → delete) revokes every key bound to it and any outstanding OAuth refresh tokens in one step.