API Keys
An API key is how anything outside the app reaches your Scenarios — CI, a script, an MCP client. Each key names one Project, carries its own scopes and an optional expiry, and can be revoked on its own without disturbing the others. The token is shown once, at creation.
Workspace admins manage keys from account (avatar → Workspace → API keys).
The four scopes
Section titled “The four scopes”A key carries any combination of four scopes:
| Scope | What it buys |
|---|---|
Read (scenarios:read) |
List, search and read Scenarios, their verification history, and this Workspace’s Projects. |
Write (scenarios:write) |
Change any part of a Scenario: create one, edit its title, place, parent or drift note, replace its path and evidence, and move its lifecycle status, including retiring it. |
Record verification outcome (scenarios:verify) |
Open a verification pass, attach evidence about the Scenario as a whole, and close it. |
Record path-step findings (scenarios:steps) |
Record what was found at individual path steps, with evidence. |
Why the two verification scopes are separate
Section titled “Why the two verification scopes are separate”This is the one distinction worth reading twice. Closing a pass is what moves a Scenario to Fit or Gap — so a key holding only Record path-step findings can record everything it saw at each step and still cannot declare the Scenario a fit. A key holding only Record verification outcome can rule on a pass but cannot rewrite the step findings it is ruling on.
What that buys: a CI harness reporting per-step observations cannot declare a Scenario a fit on its own, and a reviewer bot publishing the verdict cannot quietly edit the evidence underneath it. Either is useful alone; a key that runs a whole pass end to end holds both.
Opening and abandoning a pass take either scope — a step-recording agent may arrive first and needs a pass to record into, and abandoning frees the one-open-pass slot it took. Neither touches verification status.
What a key can never do
Section titled “What a key can never do”No key can create, list or revoke a key. There is deliberately no admin scope and no wildcard, so a leaked key cannot mint itself a replacement or hide its own tracks. Key management is a human, admin-only action in the app.
A key acts in one Project, chosen when you create it, and it is not a stand-in for you — it does not inherit your Project roles. One Project is not a restriction bolted on: everything a Scenario touches lives inside a single Project. Its path, the chains into and out of it, its nested children and its verification passes are all Project-local, so there is nothing for a key to do across two. Deleting a Project deletes its keys with it.
Creating, testing and revoking
Section titled “Creating, testing and revoking”Open API keys, click New key, give it a name you’ll recognise later, choose the Project it acts in, tick the scopes it needs, and pick an expiry (30 days, 90 days, a year, or never).
The token appears once, prefixed adk_live_. Copy it then — it is stored only
as a one-way hash, so nobody, including us, can read it back. Test key
right there is the only moment it can be checked at all.
Revoke stops a key immediately and permanently. Revoked keys stay listed so the activity log keeps pointing at something real. Rotating means creating a new key and revoking the old one, which is the point: the two never have to happen at the same instant.
Using a key
Section titled “Using a key”- With MCP — send it as a bearer token to the MCP endpoint; the endpoint
needs no
workspaceId, because both the Workspace and the Project come from the key. See Using the MCP Server. - With the REST API — send it as a bearer token to the API base URL. See REST API.
The key decides what an agent is even offered: MCP’s tools/list returns only
the tools the key can call, so a Read-only key is never shown a tool it would
be refused on.
Replacing the old Workspace token
Section titled “Replacing the old Workspace token”The single per-Workspace MCP token still works, and is treated as holding all
four scopes across every Project in its Workspace, so nothing breaks today. It
is being retired on 18 December 2026: responses authenticated with it
carry Deprecation and Sunset headers, and its use is noted in the
Workspace activity log once a day.
Migrating is a one-line change — create a key, swap the Authorization
header, and drop the workspaceId parameter.
API keys are included on every plan, the same as MCP server access.