Skip to main content
POST

Authorizations

​
Authorization
string
header
required

Primary scheme: Authorization: Key <key_id>:<secret>.

Body

application/json
​
name
string | null

Human-readable label for the key.

​
scopes
enum<string>[] | null

Scopes granted to the key; omitted means full access.

Least-privilege grants carried by v3 API keys.

Stored as text[] on api_keys; NULL scopes means full access (legacy keys). Scopes are stored as text so new least-privilege surfaces can be introduced without a database-enum migration.

Available options:
jobs:read,
jobs:write,
models:read,
files:write,
webhooks:manage,
log_drains:manage,
usage:read,
keys:manage
​
kind
enum<string>
default:personal

personal (default) dies with the member; service is workspace-shared, OWNER/ADMIN-managed, and survives member removal.

Available options:
personal,
service
​
workspace_id
string | null

Target workspace; omitted means the authenticating key's workspace.

​
expires_at
string<date-time> | null

ISO-8601 instant the key stops authenticating; omitted means it never expires.

Response

Successful Response

​
key_id
string
required

The key's public identifier.

​
credential
string
required

The full <key_id>:<secret> pair — a valid Bearer credential. Returned exactly once, at creation; store it now.

​
kind
enum<string>
required

Personal keys die with the member; service keys belong to the workspace.

Available options:
personal,
service
​
name
string | null

Human-readable label for the key.

​
scopes
string[] | null

Scopes granted to the key; null means full access (a legacy key predating scopes).

​
workspace_id
string | null

The workspace the key bills and acts in.

​
expires_at
string<date-time> | null

ISO-8601 instant the key stops authenticating; null means it never expires.

​
created_at
string<date-time> | null

ISO-8601 instant the key was created.