Keys and scopes
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 --deviceasks you to approve a code in Kabu, then saves a key for that computer. Nothing is copied or pasted. The plugin,kabu mcpand everykabucommand use it. - For a service or CI: create one in the console, or with
POST /v2/api_keysfrom a key holdingkeys: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 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. Nor can one key hold
messages:write with answers:delegate (400 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.