Authentication and scopes

Every request carries an API key as a bearer token:

curl https://api.kallabot.com/v1/agents \
  -H "Authorization: Bearer kb_live_7k2m9xq4ab3c_tq4w..."

A missing, malformed, unknown, revoked or expired key always gets the same answer, 401 with code unauthenticated. The API never tells you which part was wrong, so a guessed key learns nothing.

Two kinds of key

Kind	Looks like	Acts as	Use it for
Workspace key	`kb_live_…`	The workspace (a service account)	Automations: your backend, a CRM sync, a cron job.
Personal key	`kbp_live_…`	The person who created it	Acting as a teammate: live call control, notes, requests made in someone’s name.

A personal key is logged under its owner’s name in the audit log, and can never do more than its owner’s current role allows: demote the person and their key shrinks with them. It stops working the moment they leave the workspace or are suspended (401, or 403 key_owner_inactive). Some operations act as a person and need a personal key. They’re marked x-requires-personal-key in the spec and “Needs a personal key” in the API reference. A workspace key gets 403 personal_key_required:

Whispering to the agent, listening in and taking over (/whisper, /operator)
Call notes
Asking for a number we don’t stock (POST /v1/numbers/requests) and asking for minutes (POST /v1/minutes/requests)
Transferring a call to a typed number (to). Workspace keys may transfer only to the agent’s configured destinations (destination_id).

Key format

kb_live_7k2m9xq4ab3c_tq4wz6r2...
│  │    │            └── secret: 32 random bytes, base32
│  │    └─────────────── lookup: 12 characters, safe to show and log
│  └──────────────────── environment
└─────────────────────── kb = workspace key, kbp = personal key

Kallabot stores only a peppered SHA-256 hash of the key. Nobody at Kallabot can read it back, and there is no “show key” button. If you lose a key, make a new one.
The dashboard shows the first characters (kb_live_7k2m) and the last four, so you can tell keys apart.
Old sk_ and bn- keys from the previous platform no longer work.

Secret scanners can match the kb_live_ prefix. If a key ever lands in a commit or a log, revoke it at once in Settings → For developers → API keys.

Create a key

Keys are created in the dashboard, by a person, never through the API. A leaked key that could mint new keys would be impossible to contain, so the key endpoints accept only a signed-in session. Calling them with an API key returns 403 wrong_auth_plane.

Open the keys page

Settings → For developers → API keys. Workspace keys need the owner, admin or developer role. Anyone can make personal keys for themselves under Your personal keys; owners and admins can also see their teammates’ personal keys.

Name it after what uses it

For example Website lead form or CRM sync. One key per integration makes revoking one painless.

Choose its access

Pick a preset (below). A key can never hold a scope the person creating it doesn’t have.

Choose its lifetime

30 days, 90 days or 1 year. Every key expires; the longest a key can live is one year.

Copy it once

The full key is shown in this one response and never again.

Access presets

Preset	Scopes	Use it for
Full access	Every scope the workspace’s API allows	Trying things out. Avoid in production.
Place calls	`agent:read`, `call:read`, `call:create`, `call:control`, `webcall:create`	A backend that starts phone and browser calls and checks how they went.
Read only	`agent:read`, `call:read`, `number:read`, `tool:read`, `billing:read`, `webhook:read`	Dashboards and reporting. Changes nothing.
Call data	`agent:read`, `call:read`, `call:content`	Copying calls with transcripts and summaries into a CRM or warehouse.
Webhooks	`webhook:read`, `webhook:write`	Managing webhook endpoints from code.

Scopes

A scope answers “may this key do this kind of thing at all?”. Each operation in the API reference lists the scopes it needs, and the OpenAPI spec carries them as x-required-scopes. A key missing one gets 403 insufficient_scope, and the detail names what’s missing.

Scopes decide what a key may do. Which rows it can see is decided separately. An API key sees the whole workspace, unless its access was narrowed to specific agents, in which case it can only use and see those agents.

Agents

Scope	Allows
`agent:read`	List and read agents, their versions, and validate a config without saving it.
`agent:write`	Create agents, edit drafts, revert to an older version, edit an agent’s WhatsApp copy.
`agent:publish`	Publish a draft so callers hear it.
`agent:archive`	Archive an agent. Archived agents stop taking calls; their history stays.

Calls

Scope	Allows
`call:read`	List and read calls, call events, tags, saved views and tool runs. Phone numbers come back masked.
`call:create`	Place outbound calls, and create, move, confirm or cancel scheduled calls.
`call:control`	Cancel or hang up a call, send the agent a whisper, and (for people) listen in, take over or transfer.
`call:content`	Read transcripts, recordings, summaries, extracted fields and unmasked numbers. Kept separate on purpose: reading the call log is not the same as hearing a client.
`call:export`	Download the call log as CSV.
`call:annotate`	Tag calls, mark them reviewed or archived, and write notes.
`webcall:create`	Start a browser voice call with an agent.

Chat

Scope	Allows
`inbox:read`	Read WhatsApp, Messenger, Instagram and web chat threads, notes, customer history, bookings and inbox settings.
`inbox:write`	Change a thread’s status, assignee, priority and tags; manage quick replies and inbox settings; ask for a fresh summary. Sending replies is dashboard-only for now.
`webchat:read`	Read website chat widgets.
`webchat:write`	Create, edit, publish and delete widgets, and rotate their public key.

Knowledge and tools

Scope	Allows
`knowledge:read`	List and read knowledge sources, preview a Google Sheet’s columns, check indexing status, search knowledge, preview listings, read catalog items.
`knowledge:write`	Add, rename, edit and delete sources; resync, reindex or schedule refreshes; import a catalog, edit catalog items.
`tool:read`	List and read tools, their run history and saved credentials (never the secret itself).
`tool:write`	Create, edit, test and delete tools; probe MCP servers and approve their tools; save, rotate and revoke credentials.

Numbers

Scope	Allows
`number:read`	Countries, available numbers, your lines, orders, port-ins, SIP trunks and caller numbers.
`number:write`	Buy numbers, change a line’s agent and settings, choose caller numbers, connect SIP trunks, start port-ins.
`number:release`	Release a number. This can’t be undone: the number goes back to the carrier.

Webhooks and minutes

Scope	Allows
`webhook:read`	List endpoints, deliveries and the event catalogue.
`webhook:write`	Create, edit, test, enable and delete endpoints; rotate secrets; retry and recover deliveries.
`billing:read`	Read minutes balances.
`billing:write`	Move minutes between the workspace pool and people.

Dashboard-only scopes

These exist for people signed in to the app. They are not part of the public API and API keys don’t use them: apikey:read, apikey:write, audit:read, audit:export, analytics:report, provider:read, call:listen, whatsapp:read, whatsapp:content, whatsapp:write, whatsapp:reply.

Actions only a person can take

Some actions need a person behind them, even with call:control. Use a personal key for them: whispering, listening in, taking over, transferring to a typed number, and call notes. Saved call views also belong to a person.

IP allowlist

Limit where your keys can be used from in Settings → API keys → Allowed IP addresses. Add up to 20 addresses or ranges (CIDR, like 203.0.113.0/24). A request from anywhere else gets 403 ip_not_allowed, even with a valid key. An empty list means any address.

Rotate a key

Click Roll on a key to rotate it without downtime:

Roll the key

Kallabot issues a new key with the same name, scopes, environment and lifetime as the old one. The new key is shown once.

Deploy it within 24 hours

The old key keeps working for 24 hours, so you have time to switch every place that uses it.

Watch the old key go quiet

The keys list shows each key’s last used time. After 24 hours the old key stops on its own.

Behind the button, rotation accepts a grace period of 0 to 72 hours (grace_hours, default 24), where 0 retires the old key immediately. The dashboard always uses 24 hours. If a key may have leaked, don’t roll it. Revoke it: it stops within seconds, everywhere. Then create a new key. Give a short reason when you revoke; it’s kept in the audit log.

Other ways a key stops working

What happened	Result
The key expired or was revoked	`401 unauthenticated`
Its service account was disabled	`401 unauthenticated` (every key under it stops at once)
The service account’s scopes were narrowed until none were left	`403 no_scopes`
The workspace was suspended	`403 organization_suspended`

Get started

Essentials

Build

Webhooks

Policies

Authentication and scopes

Two kinds of key

Key format

Create a key

Access presets

Scopes

Agents

Calls

Chat

Knowledge and tools

Numbers

Webhooks and minutes

Dashboard-only scopes

Actions only a person can take

IP allowlist

Rotate a key

Other ways a key stops working

​Two kinds of key

​Key format

​Create a key

​Access presets

​Scopes

​Agents

​Calls

​Chat

​Knowledge and tools

​Numbers

​Webhooks and minutes

​Dashboard-only scopes

​Actions only a person can take

​IP allowlist

​Rotate a key

​Other ways a key stops working

Two kinds of key

Key format

Create a key

Access presets

Scopes

Agents

Calls

Chat

Knowledge and tools

Numbers

Webhooks and minutes

Dashboard-only scopes

Actions only a person can take

IP allowlist

Rotate a key

Other ways a key stops working