Authentication

How to authenticate with the KaiCalls API, manage API keys, and understand scopes and rate limits.

Overview

Protected business API operations use a Bearer token in the Authorization header. Signup is public; key management requires the owner's dashboard session. Check each operation's security declaration in the public OpenAPI contract before authenticating.

API Key Format

KaiCalls API keys follow a prefixed format that identifies the environment at a glance:

Live keys: kc_live_<secret>

The only prefix issued today. Telecom operations use live infrastructure and consume the account's trial allowance or plan usage.

Test keys: kc_test_<...> Not yet available

A separate sandbox is not available yet. Use mocked responses in automated tests. A dedicated demo workspace still uses live services; agree on test destinations before placing calls or sending messages.

Keys are SHA-256 hashed before storage. The raw key is shown only once at creation — copy it immediately.

Authentication Header

For protected business API operations, include your API key using the Authorization header:

Authorization: Bearer kc_live_your_key_here

Creating API Keys

For an existing account, keys are created in the dashboard or via the session-authenticated /v1/keys endpoint. Both use the browser session — an existing API key can neither mint another one nor widen its own scopes.

Bootstrapping your first key needs neither a session nor a card. The public POST /v1/signup endpoint defaults to activation_mode: "otp", which returns a live key once the owner confirms the six-digit code emailed to them. That key is read-only unless you pass api_key_scopes in both OTP requests. Card capture belongs to the optional "payment" mode, not to key issuance.

New partners can follow the partner onboarding guide to get a referral code and request setup permissions during email-verified signup.

Example request using an API key:

bash

curl https://www.kaicalls.com/api/v1/agents \
  -H "Authorization: Bearer kc_live_abc123..."

Scopes

Every API key is granted a set of scopes that control which endpoints it can access. Unless specified at creation, new keys receive the read-only default set (workspaces:read, numbers:read, agents:read, communication-runs:read, calls:read, sms:read, webhooks:read, events:read) — request write scopes explicitly. Choose only the customer scopes your integration needs. Wildcard and operator-only grants are not available through self-service key creation.

Scope	Description
`workspaces:read`	List and view accessible workspaces
`workspaces:write`	Create and update workspace details
`agents:read`	List and view agents
`agents:write`	Create and update agents
`products:read`	Read business products and offers
`products:write`	Create, update, and delete business products
`knowledge:read`	Read business knowledge
`knowledge:write`	Create, update, and delete business knowledge
`billing:read`	Read balances and included usage
`numbers:read`	List phone numbers
`numbers:write`	Assign or release phone numbers
`communication-runs:read`	Read communication runs, jobs, and attempts
`communication-runs:write`	Validate, preview, create, pause, or cancel communication runs
`calls:read`	List and view call records
`calls:write`	Make outbound calls
`leads:read`	List and view leads
`leads:write`	Create and update leads
`sms:read`	View SMS messages and conversations
`sms:write`	Send SMS messages
`emails:read`	View email queue
`emails:write`	Send emails
`webhooks:read`	View webhook configuration
`webhooks:write`	Configure or remove webhooks
`events:read`	Read durable communication events and webhook deliveries
`events:replay`	Replay or backfill durable communication events
`lifecycle:write`	Run lifecycle actions for provisioned workspaces
`sdr:read`	Read SDR pipeline data
`sdr:write`	Trigger SDR actions
`evals:read`	List eval scenarios and read run results
`evals:write`	Create, update, delete, and run eval scenarios

Business Scoping

Keys can be scoped to a single business_id or left unscoped (granting access to all businesses the user owns).

All tenant-touching endpoints filter by business_id — a key scoped to Business A cannot read Business B data.

Key Management

Manage keys via the session-authenticated /v1/keys endpoints:

Action	Method	Auth
Create	`POST /v1/keys`	Session auth required
List	`GET /v1/keys`	Session auth required
Update	`PATCH /v1/keys`	Session auth required
Revoke	`DELETE /v1/keys?id=<key_id>`	Session auth required

Keys can have an optional expires_at timestamp. Expired keys return 401 Unauthorized.

Rate Limits

Endpoint	Limit
`/v1/signup`	5 requests per IP per hour
All list endpoints	Max 100 results per request (except `/v1/usage` at 500)
`/v1/transcripts`	Max 50 results per request

See the Errors reference for details on error responses, or return to the full API reference.