Skip to main content

API Keys

Programmatic tokens (nat_sk_…) scoped to a project or account.

Overview​

Keys are created and scoped through the API (or app) to a project — the default — or the whole account, plus a set of capabilities. The raw secret is returned exactly once, at creation (or rotation); every other read returns only key_prefix. A project-scoped key cannot create a project or add a member, which is why Create a provider and Invite a colleague start from an account-wide one.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → API Keys.

Data Model​

ApiKeyRecord​

FieldTypeDescription
idstringPublic API key ID (key_ prefix).
namestringHuman-readable label.
key_prefixstringLeading characters of the raw key, for identification.
scopeproject | accountWhether the key is scoped to one project or the whole account.
project_idstring, nullableThe project this key is scoped to; null for account-scoped keys.
capabilitiesstring[]The capabilities this key is narrowed to, each the one an operation needs (<module>:<OperationId>); a call outside them is 403. Empty means the key reaches whatever its holder's membership reaches.
created_atstring (date-time)
last_used_atstring (date-time), nullableWhen the key was last presented; null if never used.

Key Concepts​

The secret is write-only​

ApiKeyCreated (the create/rotate response) is the only shape that includes the raw secret (nat_sk_…); it is never returned again. Losing it means rotating the key.

Capabilities narrow a key​

Every operation needs one capability, <module>:<OperationId>: GET /v1/projects/{project_id}/secrets needs secrets:ListSecrets, and POST /v1/api-keys needs api-keys:CreateApiKey. A few runtime operations share a capability: a session's need agents: ones (agents:CreateSession), and a resource's tag reads and writes need its Get… and Update…. The Create… and Update… capabilities of tools, agents, triggers and ai-providers also let the key reference the project's secrets in what it writes. A capability that runs a generation (agents:CreateAgentGeneration, agents:SendSessionMessage, agents:SubmitSessionToolOutputs, conversations:GenerateConversationMessage) also lets its tool calls use the project's OAuth connections. agents:CreateAgentGeneration and agents:SubmitSessionToolOutputs also carry generations:ResumeGeneration, which resuming a paused generation needs beside them. knowledge:SearchKnowledge carries embeddings:CreateEmbeddings, which embedding the query needs.

An operation this API serves itself reaches the runtime on the key's own bound, carrying only the runtime calls it makes: the project's Get…, Update…, Pause… and Resume… capabilities carry the runtime's project actions of the same name, the usage-threshold list carries usage:ListThresholds and its create and delete usage:ManageThresholds, and a channel conversation's delete and transcript carry its session's. A narrowed key cannot remove a guardrail through the project's guardrail_ids: the runtime asks guardrails:DetachGuardrail, which no capability carries.

A key with a non-empty set reaches only the operations it names; any other call answers 403, naming the missing capability. A key with an empty set reaches whatever its holder's membership reaches. A FORBIDDEN the runtime answers because the key's set does not hold an action names the key: meta.denied_by is { "type": "api_key", "id": "<key id>" }. An unknown capability is 400. A change to the set holds from the key's next call. The runtime decides every project operation of the runtime's modules and of channels, channel routes, addresses and MCP servers; when it cannot be asked, the call is 502.

A refusal this API decides on a record before relaying a call, such as a managed provider's read-only fields, reaches a narrowed key only when the key can read that record itself; otherwise the call answers 403 FORBIDDEN saying nothing about it.

Capabilities also bound what an agent the key runs does through a builtin tool: a key narrowed to agents:CreateAgentGeneration that runs an agent bound to one reaches only the tool's actions the key also names. See builtin tools. Such a key needs tools:CallTool for a run_as: caller agent to call any http, mcp or pipeline tool (Calling a tool needs tools:CallTool).

A narrowed key cannot widen itself: it may create or patch a key only to a non-empty subset of its own set, omitting capabilities on create gives the new key its own set, and rotating a key wider than it answers 403.

Nor through what it writes. Creating or editing an MCP server needs tools:CallTool for every tool it exposes, and storing a channel, route or address action that runs an agent needs agents:CreateAgentGeneration. The runtime answers both for the key's own credential; a refusal is 403 FORBIDDEN naming the action and resource in meta. An edit is checked against what it leaves, kept bindings included.

Rotation​

POST /v1/api-keys/{api_key_id}:rotate issues a new secret for the same key record and invalidates the old one immediately.

A connected app cannot mint one​

Creation and rotation are refused for an OAuth access token and for an Assistant turn, with 403 FORBIDDEN. Both credentials are re-read on every request so that disconnecting an app, or revoking a link, stops it immediately — and a nat_sk_… key minted beforehand would keep working afterwards, which is the one thing that immediacy exists to prevent.

Reading and revoking keys stay available to a connected app: both narrow what exists rather than widening it. Minting a key is a human act, or an act of a credential whose own authority hangs off no grant.

Account routes need an account-wide key​

A project-scoped key reaches only two routes under /v1/users/me: GET /v1/users/me and the stops, which it sees for its own project only. Every other account route — billing, usage, credit, statements, plan, top-ups, payment method, auto-recharge, profile edits — answers 403 FORBIDDEN. A connected app confined to some projects is refused the same way, and no connected app may change the plan, buy credit, or touch the saved card or auto-recharge. See Users.

Deleting a key stops the work it started​

DELETE /v1/api-keys/{api_key_id} also revokes the key in the runtime, in every project it may have acted in, before it answers. A generation the key started and that is paused on a client tool then calls no tool on resume: each call fails 409 WORK_AUTHORITY_MISSING. If the runtime does not record the revocation, the delete answers 502 UPSTREAM_UNAVAILABLE and the key stays live; retry it.

Removing the key's owner from a project revokes it there the same way (Projects).

Deleting a project revokes its keys​

DELETE /v1/projects/{project_id} revokes every key scoped to that project as part of the same operation. A revoked key stops authenticating immediately and every call with it returns 401 UNAUTHORIZED — a clear signal that the credential's project is gone, rather than a 404 that reads like a wrong or mistyped id. There is no recovery for a project-scoped key once its project is deleted: mint a new key against a different project instead.

Examples​

naturali create-api-key --name ci-deploy --project-id proj_V1StGXR8Z5jdHi6B