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://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. New keys receive all default scopes unless restricted at creation. Use * for full access:

Scope	Description
`agents:read`	List and view agents
`agents:write`	Create and update agents
`calls:read`	List and view call records
`calls:write`	Make outbound calls
`leads:read`	List and view leads
`leads:write`	Create and update leads
`numbers:read`	List phone numbers
`sms:read`	View SMS messages
`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
`sdr:read`	Read SDR pipeline data
`sdr:write`	Trigger SDR actions
`*`	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
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.