API keys

What a key is, the two scopes, and how to revoke one.

A key is how another system proves who it is when it sends conversations in. Open Setup, then API keys, to see the keys this workspace has.

A platform webhook needs no key at all. It authenticates with a token in its own URL, which the webhooks page explains.

The two scopes

A key carries one scope, and that is the most it can ever do. There is no admin scope, so no key can change a setting.

Ingest	Sends conversations and events in, to /ingest/v1/events and /ingest/v1/import. It cannot read any conversation back. This is the scope almost everyone wants.
Read	Reads conversations, metrics, findings and scores. It cannot change or delete anything.

A key can also be limited to one client, so a partner sees only their own conversations. The list says so on every key that carries the limit.

Create one

Name the key after the system that will use it, pick a scope, and copy the token. The token comes back once, at creation, and never again.

The list shows the first characters of the token and nothing else. That prefix is all we keep of the key itself. The rest is stored as a hash, so a lost key is replaced rather than looked up.

Replace one

Note: There is no rotate button. To replace a key, create the new one, move whatever uses it across, then revoke the old one. In that order the sending system is never left without a working key.

Revoke one

Same screen. A revoked key stops working from its next request, and nothing brings it back. Create a new key instead.

Using it

Both keyed endpoints read the key from the standard authorization header.

http

POST /ingest/v1/events
Authorization: Bearer ak_live_...
Content-Type: application/json

A live key starts with ak_live_. A test key starts with ak_test_.