Authentication

Every request to the REST API and the inbound webhook is authenticated with an API key that is scoped to a single company. A key can never act on another company's data.

Creating an API key

Sign in to the app and open Company → API keys at https://app.callanalyticsapi.com/company/api-keys. Click Create key, give it a label, and choose its scopes. The raw key is displayed once, at creation time — copy it immediately and store it in your secret manager. We only keep a hash, so a lost key cannot be recovered, only rotated.

Key format

A key looks like cc_3a91f8e2_secret: a cc_ prefix, a short public id, then the secret. Only the public prefix (e.g. cc_3a91f8e2) and a hash of the secret are stored — the dashboard shows the prefix so you can tell keys apart, never the secret.

Whether a call is processed by the mock or the live AI pipeline is a server-side setting, not a property of the key — the request/response shapes are identical either way.

Sending the key

Pass the key on every request using either header. Both are equivalent.

Authorization: Bearer

curl https://api.callanalyticsapi.com/v1/calls \
  -H "Authorization: Bearer cc_3a91f8e2_your_api_key"

X-Api-Key

curl https://api.callanalyticsapi.com/v1/calls \
  -H "X-Api-Key: cc_3a91f8e2_your_api_key"

If the header is missing, the API returns 401 with {"error":"unauthorized","message":"Missing API key."}. If the key is unknown, expired, or revoked, you get 401 with "Invalid, expired, or revoked API key.".

Scopes

Each key carries a set of scopes that limit what it can do. Grant the least privilege your integration needs.

A key without a required scope receives 403 with {"error":"forbidden"}.

Revocation & rotation

Revoke a key from Company → API keys at any time. Revocation is immediate — the next request with that key returns 401. To rotate without downtime, create a new key, deploy it, then revoke the old one.