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>
For production use. Actions are real.
Test keys: kc_test_<44 chars base64url>
For development and 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_hereCreating API Keys
Keys are created in the dashboard or via the session-authenticated /v1/keys endpoint.
Example request using an API key:
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 13 default scopes unless restricted at creation:
| 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 | 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 |
sdr:read | Read SDR pipeline data |
sdr:write | Trigger SDR actions |
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.