Getting started

Authentication

The REST API authenticates with a secret API key, sent as a bearer token. Webhooks we send you are authenticated differently — with a signature — covered in Voice webhooks.

Bearer tokens

Put your key in the Authorization header on every request:

Authorization: Bearer sk_live_...

A missing, revoked, or unknown key returns 401 Unauthorized. Keys belonging to a suspended account are also rejected.

Managing keys

Create keys in the portal under API Keys, or over the API. The full secret is returned only when the key is created — we store a hash, so we can never show it again. If you lose it, revoke the key and create a new one. Creating a key from the portal (not the API) requires a fresh one-time code from your authenticator app.

# create a key
curl https://sauti-pbx.services.co.ke/api/keys/create \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "production server" }'

# → { "uuid": "...", "prefix": "sk_live_ab", "key": "sk_live_abcd...", ... }
#   the full "key" is shown this one time only

Each key has a short prefix so you can tell them apart in listings, plus a last_used_at stamp. See the Keys API for list and revoke.

Keep secrets on the server

Your API key is a full-access credential — treat it like a password:

• Never ship it in browser JavaScript, a mobile app, or a public repo.
• For the browser, mint a short-lived token instead: a stream token to watch events, or a phone token to place a call from a softphone. Both are minted server-side and expire quickly.
• Rotate keys if one may be exposed — revoke the old one and switch to a new one.