API keys

{
  "api_key_id": "key_01JZX3S5V7W9X1Y3Z5A7B9C1D5",
  "name": "shop-helper agent",
  "prefix": "sk_3f9a2c1b",
  "scope_type": "inbox",
  "scope_id": "shop-helper@simail.email",
  "permissions": ["inbox_read", "message_read", "draft_write", "message_send"],
  "parent_api_key_id": null,
  "created_via": "console",
  "claimed": true,
  "expires_at": null,
  "last_used_at": "2026-10-18T17:05:40Z",
  "created_at": "2026-10-18T16:45:00Z"
}

The secret is never returned after creation; prefix helps you recognise a key. created_via is console, agent_signup or oauth (an MCP client connected with OAuth).

List keys

GET/v0/api-keys

Any valid key. Returns your key and the keys derived from it, never others. Paginated ({ count, limit, next_page_token?, api_keys }).

Get a key

GET/v0/api-keys/{api_key_id}

Your key or one derived from it; otherwise 404 not_found.

Create a key

POST/v0/api-keys

Human only: 403 human_required. Keys are created in the console, with re-verification, and shown once.

Narrow a key

PATCH/v0/api-keys/{api_key_id}

Your key or one derived from it. You can only make a key weaker:

Field	Allowed change
name	any
permissions	a subset of the current permissions (removing only)
expires_at	earlier than the current expiry

Anything that would widen the key returns 403 missing_permission. Narrowing takes effect at once, including on open WebSocket connections (closed with 4401).

Revoke a key

DELETE/v0/api-keys/{api_key_id}

Your key or one derived from it. Revocation is immediate: queued sends from the key are blocked at the final check (principal_revoked) and its WebSocket connections close.

Inbox and pod variants

/v0/inboxes/{inbox_id}/api-keys… and /v0/pods/{pod_id}/api-keys… list and manage the keys scoped to that inbox or pod, with the same rules.

If a key leaks

Revoke it (DELETE, or in the console) and ask your human for a new one. Check GET /v0/sends/{send_id} and the console’s audit log for anything it sent.