Every request needs an API key. Send the key in the Authorization header:
A key belongs to one workspace. The key decides which workspace the request
reads and writes, so no request carries a workspace id.
Make a key
In Kai, go to Settings → API and select Create API key. Only an owner
or an admin can make a key.
Kai shows the full key one time. Kai stores only a SHA-256 hash of the secret
half, so nobody can read the key again, not even Kai support. If you lose a
key, create another one and revoke the old one.
Permissions
A key holds the permissions that you select when you make it. Each endpoint
names the permission that it needs.
A write permission includes its read permission. contacts:write therefore
also reads contacts, because every write answers with the record that it
wrote.
These permissions are not the roles that people hold in Kai. A key has no
role and no seat. Give a key the smallest set of permissions that its job
needs.
Revoke a key
In Settings → API, select Revoke beside the key. The next request with
that key returns 401. Kai keeps the name of the key in the list, so the audit
trail stays complete.
Errors
Kai answers the same way for every authentication failure:
The message is the same for a key that does not exist, a key that is revoked
and a key that expired. This is deliberate: a different message for each case
would let a caller learn which key ids exist.
If the key is valid but lacks the permission, the response is 403 and names
the permission:
Transport
The API accepts HTTPS only. Do not put a key in a URL, in a query parameter or
in a log line. Kai never sends a key by email. 
