Authentication
API keys
All Chatty API requests require a Bearer API key in the Authorization header:
Authorization: Bearer chatty_sk_<your-key>
Keys are created per bot in Dashboard → Settings → API Keys. A bot can have multiple keys — create separate ones for different environments and revoke them independently.
API keys are shown once at creation and cannot be retrieved again. Store them in environment variables, never in source code.
Scopes
Every key carries one or more scopes controlling which endpoints it can call. Assign the minimum scopes needed.
| Scope | Endpoints |
|---|---|
chat | POST /api/v1/chat |
read | GET leads, conversations, knowledge, analytics, usage, bot details |
write | POST/DELETE knowledge, DELETE conversations |
admin | All of the above |
Embed integration
chat. Visitors send messages but can't read your data.CRM sync
read to pull leads and conversations.Content pipeline
write to add/remove knowledge sources.Internal dashboard
admin for full access.IP allowlist
Restrict a key to specific IPs or CIDR ranges. Requests from any other IP return 403.
["203.0.113.42", "10.0.0.0/8", "2001:db8::/32"]Leave the allowlist empty to allow requests from any IP. The embed widget uses a separate mechanism and is not affected.
Key management
| Method | Endpoint | Description |
|---|---|---|
POST | /api/keys | Create a new key |
GET | /api/keys?bot_id=... | List all keys for a bot |
PATCH | /api/keys/{id} | Update name, scopes, allowlist |
DELETE | /api/keys/{id} | Revoke permanently |
These require a Supabase session token (dashboard login), not an API key.
Security headers
Every response includes:
| Header | Value |
|---|---|
X-Request-ID | Unique UUID per request — include in bug reports |
X-Content-Type-Options | nosniff |
X-Frame-Options | DENY |
Strict-Transport-Security | max-age=31536000; includeSubDomains; preload |
Content-Security-Policy | default-src 'none' |