API keys and permissions

A key looks like ct_live_a1b2c3_… — the middle segment is a public prefix shown in the key list so you can tell keys apart, and the last segment is the secret half, which we store only as a hash.

Each key belongs to one organization. Every request it makes is scoped to that organization by the data layer itself, so there is no organization id to pass and no way for a key to read another tenant's records, even by guessing ids.

When you create a key you tick permissions from the same catalogue that roles use. The key gets exactly those and can never gain more. A 401 means the key is not recognised; a 403 means it is recognised but lacks the permission that endpoint requires.

You can only grant permissions you hold yourself. An HR manager who cannot read payroll cannot create a key that reads payroll — which stops a key being used to climb out of a role.

Grant the minimum. A key that only reads the directory cannot leak salaries even if it is committed to a public repository.

Keys cannot manage keys or webhooks. Every /integrations endpoint refuses an API key and requires a signed-in person in the web app. That is deliberate: a leaked key must not be able to mint a quieter replacement for itself, or point a webhook at an attacker's server.

Scopes are fixed once a key exists. To change what a key can do, create a new one with the right scopes, deploy it, then revoke the old one.

Revocation takes effect on the very next request; there is no cache to wait out. The key list shows when each key was last used and from which address, so you can confirm nothing still depends on a key before revoking it.

Set an expiry date on keys given to a contractor or a trial integration and they stop working on their own.

• Store it in an environment variable or a secret manager, never in source control.
• Never put a key in front-end JavaScript or inside a mobile app — anything a browser can read, a user can read.
• Never put a key in a URL query string; URLs are logged by proxies, browsers and error trackers.
• Use a separate key per integration, so revoking one does not break the others.