Sign in
keys

Create Key

Create a new API key in the caller's organization.

Requires master key authentication.

If user_id is provided, the key will be associated with that user (creates user if it doesn't exist). If user_id is not provided, the key is associated with the shared "default" user, which is created on first use. Keys without an explicit owner therefore share one identity, and so share budget, usage, and files.

workspace_id names a workspace in the caller's organization, and omitting it mints into that organization's default workspace. A key resolves that organization's provider credentials and bills there, so minting into another organization's workspace would spend its budget on its credentials.

post/v1/keys

Request body

allowed_modelsstring[] nullable

Model allow-list: null = any model, [] = deny all, or canonical instance:model entries (with instance:* / instance:prefix* wildcards).

capture_agent_telemetryboolean nullable

Per-key override of the deployment-wide capture_agent_telemetry setting: null (default) inherits it, true always stores this key's coding-agent telemetry, false always discards it. Covers both behavioral events (tool_result, tool_decision, user_prompt, api_error) from POST /v1/logs and outcome-metric data points (lines of code, commits, pull requests, active time) from POST /v1/metrics. Usage capture and billing are unaffected either way.

exclude_from_budgetboolean

When true, requests on this key are logged with cost but never reserved, reconciled into the user's spend, or gated by budget.

expires_atstring date-time nullable

Optional expiration timestamp

key_namestring nullable

Optional name for the key

metadataobject

Optional metadata

reject_user_mismatchboolean nullable

Per-key override of the deployment-wide reject_user_mismatch setting: null (default) inherits it, true always rejects a request naming a different 'user', false always accepts it. Spend binds to this key's own user either way.

user_idstring nullable

Optional user ID to associate with this key

workspace_idstring uuid nullable

Workspace this key belongs to, which must be one in the caller's organization. Omitted means that organization's default workspace. A key belongs to exactly one workspace: requests on it are scoped and billed there, so the workspace is read off the key rather than off a request header.

Response

Successful Response

allowed_modelsstring[] nullable required
capture_agent_telemetryboolean nullable required
created_atstring required
exclude_from_budgetboolean required
expires_atstring nullable required
idstring required
is_activeboolean required
keystring required
key_namestring nullable required
key_prefixstring nullable required
metadataobject required
reject_user_mismatchboolean nullable required
user_idstring nullable required

Changes