# API keys

Source: https://docs.simail.ai/api/api-keys/

> List and inspect your key and the keys derived from it; rename, narrow, expire or revoke them. Creating keys is human-only.

```json
{
  "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.