Skip to main content
POST
JavaScript
A key belongs to one workspace and carries scopes that decide which endpoints its token can call. Only metadata.name is required, but a key with no spec.permissions can call only scope-free endpoints, so in practice the scopes are the point of the call.

The token shows once

spec.token is in this response and in the rotate response, and nowhere else. A get or list omits it. Lose the value and rotation is the recovery path, which invalidates the old token in the same motion.

Scopes are deny by default

Each entry in spec.permissions is a resource:verb string. Resources are agents, objectives, tools, memory, api_keys, workspaces, widgets, widget_sessions, secrets, and account; verbs are read and manage, where manage implies read. "*" is the explicit full-access grant, and nothing less than that grants everything. Two behaviors worth knowing before you script key management:
  • The stored set is normalized: objectives:manage swallows objectives:read, so the key you read back can list fewer scopes than you sent.
  • secrets and account support only manage.
The scope reference maps every endpoint to the scope that gates it.

Keys are born enabled

A new key starts in STATE_ENABLED and works immediately. state is read-only; disable and enable are the actions that move it, and a PATCH cannot.

API key scopes

The grammar, the endpoint map, and how a denial reads.

Rotate an API key

A fresh token, the old one dead, one call.

Update an API key

Rename it or change its scopes in place.

Store and use secrets

Where a minted token belongs on the other side.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId
string
required

The workspace this API key belongs to (path).

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

Body

application/json
metadata
object
required

CreateAccountResourceMetadata contains the user-provided fields for creating an account-scoped resource. Read-only fields (id, account_id, profile_id) are excluded since they are set by the server.

spec
object
required

Configuration for an API key.

Response

OK

An API key. Every key belongs to exactly one workspace and is managed via the workspace-scoped API key routes. The only exception is the system-managed global account key, which spans all workspaces and is managed via the account global_api_key routes.

metadata
object
required

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

spec
object
required

Configuration for an API key.

state
enum<string>
required
read-only

The current lifecycle state of the API key. Output only. Keys are created STATE_ENABLED; use the :disable and :enable actions to transition between states.

Available options:
STATE_UNSPECIFIED,
STATE_ENABLED,
STATE_DISABLED
info
object