Authentication

Every request to the API carries a key that identifies your account. The key allows one thing only: sending recordings to that account. It does not let anyone read calls, results or settings.

1. In the app, go to Integrations and, on the API card, click Create a key.

2. In What will use it, type the name of the system that will hold the key, for example “Telephony system”.

3. Click Create key and copy the key.

A key looks like this: the prefix ck_ and 48 hexadecimal characters.

ck_0123456789abcdef0123456789abcdef0123456789abcdef

Send it in the Authorization header, with the Bearer scheme:

POST /v1/calls HTTP/1.1
Host: api.caller.ee
Authorization: Bearer ck_0123456789abcdef0123456789abcdef0123456789abcdef

A request with no key, with a mistyped key or with a revoked key gets a 401:

{ "error": { "code": "unauthorized", "message": "Missing or invalid API key." } }

You can have up to 10 active keys. Give each system its own: the telephony system, the script that loads your old recordings, your own test environment. That way, if a key leaks or a system is retired, you revoke that key and the rest keep working.

For each key, the list shows its name, its first characters, when it was created and when it was last used. A key that still says “Never used” after months is a good candidate to revoke.

In the list, click Revoke and confirm. The effect is immediate: the next request with that key gets a 401. This cannot be undone. If you revoked the key by mistake, create a new one.

To replace a key without interrupting the service:

1. Create the new key.
2. Put it in your system and check that recordings keep arriving.
3. Revoke the old key.

• Out of the code. Put it in an environment variable or in the secrets manager you use, not in the repository.
• Only on the server. Do not include it in a web page or a mobile app: anyone could read it.
• Out of the logs. If you log outgoing requests, leave out the Authorization header.

If you suspect a key has ended up somewhere it should not be, revoke it first and investigate afterwards.