Getting started
Authentication
Authentication
Every call carries an API key as a bearer token:
Code
Keys are created in Settings → API & webhooks. The full key is displayed once, at creation: we keep a SHA-256 hash and the first characters, so support can recognise a key in a log without being able to use it. Lose it and you revoke it and mint another — there is no recovery, by design.
Scopes
A key carries the scopes it was created with:
| Scope | What it opens |
|---|---|
read | Every GET. |
write | Every POST, PATCH and DELETE. |
ticket:create | POST /tickets and nothing else. |
ticket:create exists for the common case of a contact form or a monitoring
system that should be able to open a ticket and never read one. Give it that
key and a leak costs you nothing but noise.
What the failures mean
They are deliberately different, because they call for different fixes:
- 401 — the key is missing, malformed, unknown or revoked. Check what you sent.
- 403 — the key is known but lacks the scope this route needs, or the workspace is suspended. Mint a key with the right scope; do not retry.
- 429 — you are over 600 requests per minute. Wait
Retry-Afterseconds.
Keeping a key safe
- Server-side only. A key in a browser or a mobile app is a public key.
- One key per integration, named after it. Revoking then costs you one integration, not all of them.
- Every call is recorded in the workspace's audit log with the key that made it, so "who did this" always has an answer.
Last modified on