Authentication
Two headers on every request:
Code
Both are required. The key identifies you, and the workspace header names the workspace the request acts in. A key is pinned to one workspace, so the two must agree. A mismatch is refused rather than silently reinterpreted.
Issue a key
Create a key under API keys in your account settings. No endpoint issues, lists or revokes one: a credential that authenticates the API is not itself issued over the API, so a leaked key cannot be used to mint another or to widen its own scope.
Only a sha256 digest is stored. The key is shown once, when you create it, and is never returned again. A lost key is replaced rather than recovered.
Key permissions
A key acts as the user who created it and can never do more than that user can. If their access is reduced, the key's access is reduced immediately.
key_permissions narrows it further, and is how a read-only integration is built:
Code
An empty array applies no narrowing at all: the key carries everything its owner has. That is rarely appropriate for an integration.
Each operation in the reference states the permission it requires, so you can assemble the smallest set that does the job.
IP allowlists and expiry
| Field | |
|---|---|
key_ip_whitelist | Addresses or CIDR ranges the key may be used from. Ranges matter, because most callers egress from a block rather than a single address. Empty means anywhere. |
key_expires | When the key stops working. Must be in the future. Empty means no expiry. |
Revoke a key from the screen you created it on. Revocation is immediate: the key stops working on its next request, with no grace period. It cannot be undone, so issue a new key instead.
Throttling on failed attempts
Repeated failures from one address are throttled. Expect this when testing key handling. It is not a new kind of failure in the key itself.
User authentication
First-party clients authenticate as a signed-in user with a bearer token instead of a key. The permission model is identical; only the credential differs. If you are building an integration, use a key.