Authentication

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

Overview

All API requests require authentication via a Bearer token in the Authorization header. The only exceptions are /v1/signup and /v1/wordpress/plugin/download, which are public endpoints.

API Key Format

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

Live keys: kc_live_<44 chars base64url>

The only prefix issued today. Every call hits live infrastructure and is billed.

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

A separate sandbox prefix is on the roadmap. Until shipped, use a dedicatedkc_live_key against a non-production business for testing.

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

Authentication Header

Include your API key in every request using the Authorization header:

Authorization: Bearer kc_live_your_key_here

Creating API Keys

Keys are created in the dashboard or via the session-authenticated /v1/keys endpoint.

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. Use * for full access:

Scope	Description
`workspaces:read`	List and view accessible workspaces
`workspaces:write`	Create, update, pause, cancel, or tear down workspaces
`agents:read`	List and view agents
`agents:write`	Create and update agents
`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
`*`	Full access (all scopes)

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.