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
| Field | Type | Description |
|---|---|---|
id | string | Public API key ID (key_ prefix). |
name | string | Human-readable label. |
key_prefix | string | Leading characters of the raw key, for identification. |
scope | project | account | Whether the key is scoped to one project or the whole account. |
project_id | string, nullable | The project this key is scoped to; null for account-scoped keys. |
capabilities | string[] | 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_at | string (date-time) | |
last_used_at | string (date-time), nullable | When 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
- CLI
- SDK
- curl
naturali create-api-key --name ci-deploy --project-id proj_V1StGXR8Z5jdHi6B
const { data: created } = await naturali.apiKeys.createApiKey({
body: { name: 'ci-deploy', project_id: 'proj_V1StGXR8Z5jdHi6B' },
});
// created.key is the raw nat_sk_… secret, returned exactly once — store it now.
curl -X POST https://api.naturali.ai/v1/api-keys \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "ci-deploy", "project_id": "proj_V1StGXR8Z5jdHi6B" }'