Authentication
One header, one key, one account. Keys carry their own permissions, their own mode, and their own lifetime.
The header
Authorization: Bearer kls_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxX-Kleos-Key is accepted as an alternative for environments where the standard header is awkward to set. Never put a key in a query string — it ends up in logs you do not control.
Key format
Keys start with kls_live_ or kls_test_. The prefix tells you the mode at a glance, and the tail includes a checksum, so a truncated or mistyped key is rejected without a database lookup — a typo and a revoked key are never confused for each other.
Kleos stores only a hash. If a key is lost it cannot be recovered, only replaced.
Permissions
Every key carries an explicit list. There is no hierarchy and no implication: customers:write does not grant customers:read. Give a key what it needs and nothing else — a key that can only read customers is worth very little to whoever finds it in a log.
| Scope | |
|---|---|
customers:read | Read your customers and their readiness. |
customers:write | Create and update customers. |
calls:read | Read calls, transcripts summaries and outcomes. |
calls:write | Place calls. The one that can spend money. |
chat:write | Use the Kleos AI chat on your customers' behalf. |
numbers:read | See the numbers assigned to your customers. |
numbers:order | Order a number. Spends your balance. |
brand:read | Read your branding. |
brand:write | Change your branding. |
events:read | Read the event history for your account. |
billing:read | Read balance and usage. |
A key without the permission an endpoint needs gets 403 scope_missing, naming the scope it lacked. That refusal appears in your console activity log too, so you are not debugging blind.
Rotation
Rotate from the console. Kleos mints the replacement and puts the old key into a 24-hour grace window: both work, so you can deploy without a gap. When the window closes the old key returns 401 key_rotated.
If a key has leaked, do not rotate — revoke. Revocation is immediate and has no grace window, because a grace window on a leaked key is just a countdown that somebody else is also holding. Kleos can also force a rotation from its side; if that happens, the replacement reaches you through your Kleos contact and the old key is already dead.
IP allowlists and expiry
A key can be pinned to a set of source addresses and given an expiry date. Both are optional and both are worth setting for a key that lives on a fixed server. Requests from outside the list are refused with 403 ip_not_allowed.
One key, one account
A key belongs to exactly one reseller account and can only ever see that account's customers. It also belongs to exactly one mode: a test key cannot read live customers, and a live key cannot read test ones. There is no parameter that crosses either boundary.