Authentication and API keys

The two scopes, what each one reaches, and how to replace a key.

A key is how another system proves who it is. Open Setup, then API keys, to see what this workspace has.

A platform webhook needs no key at all. It authenticates with a token in its own URL. How the webhook path authenticates

The two scopes

ingest	Sends conversations in, to /ingest/v1/events and /ingest/v1/import. It cannot read anything back. This is the scope almost everyone wants.
read	Reads conversations, metrics, findings and scores. Those seven endpoints and nothing else. It cannot change or delete anything.

There is no admin scope, so no key can change a setting. The Setup form issues one scope per key, though the API itself accepts a list.

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

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_.

Name the key after the system that will use it, and pick a scope.
The scope is required. There is no default.
Copy the token.
It comes back once, at creation, and never again.
To replace one, create the new key before you touch the old one.
Move whatever uses it across, then revoke the old key. In that order the sending system is never without a working key.
Revoke from the same screen.
A revoked key stops working from its next request, and nothing brings it back.

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

Note: There is no rotate button, because rotating is creating and revoking and nothing can do both at once without a window where neither works.