# Keys and scopes

> Agent, service and admin keys, what each may do, binding a key to a project or agent, test keys, and the one thing no sending key may ever do.

Every call to Kabu is made with a key, sent as `Authorization: Bearer kabu_live_sk_…`. A key carries **scopes**, which
say what it may do, and can be bound to one project or agent.

## Getting a key

- **For a computer:** `kabu login --device` asks you to approve a code in Kabu, then saves a key for that computer.
  Nothing is copied or pasted. The [plugin](/docs/plugin), `kabu mcp` and every `kabu` command use it.
- **For a service or CI:** create one in the console, or with `POST /v2/api_keys` from a key holding `keys:write`. Its
  secret is shown once.

## Presets

| Preset | For | Scopes |
|---|---|---|
| `agent` (the default) | Anything that notifies and asks | `messages:write`, `messages:read`, `sessions:write`, `sessions:read`, `claims:write`, `media:write`, `events:read` |
| `service` | Your own service answering on a person's behalf, managing recipients and webhooks | `answers:delegate`, `steer:write`, `recipients:write`, `webhooks:write`, `messages:read`, `sessions:read`, `events:read` |
| `admin` | Setting things up: projects, agents, webhooks, keys, the org | the agent scopes, and `projects:write`, `agents:write`, `webhooks:write`, `keys:write`, `org:write`, `usage:read`, `observability:read` |

A key may also list its own `scopes`, as long as they are a subset of its creator's. Each operation in the
[reference](/docs/api/messages) names the scopes it needs.

## Asking and answering never share a key

A key that can send messages (`messages:write`) can never answer for a person: answering, and minting answer links,
refuse it with `403` [`self_response_forbidden`](/docs/errors/self_response_forbidden). Nor can one key hold
`messages:write` with `answers:delegate` (`400` [`incompatible_scopes`](/docs/errors/incompatible_scopes)). So an agent
can never approve its own ask, or a sibling agent's, however it is prompted. A service that both asks and collects
answers in its own interface uses two keys.

## Narrowing a key

Pass `project` and `agent` when creating a key to bind it: it then sends only as that project and agent, and reads only
their messages. A key can create keys only narrower than itself: fewer scopes, a bound project or agent, test mode or
an earlier `expires_at`.

## Live and test keys

`kabu_live_sk_…` keys reach people. `kabu_test_sk_…` keys work the same way against your test data, but nothing is
ever delivered to a phone, and `POST /v2/test/messages/{message_id}/responses` lets a test key answer its own asks, to
try every decision in CI.

## Rotating and revoking

`POST /v2/api_keys/{key_id}/rotate` issues a new secret and keeps the old one working for a grace period you choose;
`DELETE /v2/api_keys/{key_id}` revokes a key at once. `kabu whoami` shows which key `kabu` is using.