API keys
Personal keys for scripts and integrations, narrowed to the organizations, projects and permissions you give them.
An API key acts as the user who created it, narrowed three ways:
- Organizations and projects. Each key lists the organizations it reaches, and in each either
allits projects — including ones created later — or a list of them. - Permissions. Scopes such as
issue:readorform:write, at most one per area. A key never does more than its user may: the user's own permission profile still applies, and the key can only narrow it. - Expiry. 30, 90 or 365 days, or never.
The secret is shown once, when the key is created. You can hold at most five live keys (keys that have not expired); revoke one to create another — a sixth is refused with 422. Create keys in the web app under Account → API keys, or with POST /api/account/api-keys from a session.
Using a key
Send it in the x-api-key header:
curl https://gamma.example.com/api/projects/0199f2a4-…/issues \
-H "x-api-key: <your key>"What a key reaches
Keys work the content of projects, not their administration:
- Yes: an organization's details and its project list; inside a project, the project itself, its models, views and search sets (under the key's
modelpermissions), markers, issues, forms and templates, tracked objects and dashboards — reading and writing as the key's permissions allow — plus their files, history and configuration (issue schemas, status sets). - No: your account, other keys, members, invitations, profiles, settings, jobs, and anything at organization level beyond reading it.
On any other path — your account, the admin panel — the x-api-key header is ignored and the request is treated as if it came without one: with no session it gets 401, not 403.
Each operation in the reference says API keys: yes or no, and for content routes the permission the key needs (issue.read, model.update, …).
Rate limit
Each key may make 600 requests per 60 seconds. Past that, requests with the key get 429 until the window moves on. The limit counts per key, so with five keys a person can send at most five times that.
Unused keys are revoked
A key that makes no request for 180 days — counted from its last request, or from its creation if it never made one — is revoked automatically by a daily sweep. Its owner gets an email naming the key and saying it was revoked, with a link to Account → API keys to create a new one. Anything still using the key gets 401 from then on.
Refusals
| Status | Why |
|---|---|
401 | The key is unknown, revoked, expired, or its user is banned — or the route is outside an organization or project, where the key is ignored and there is no session. |
403 | Inside an organization or project: the route does not take keys, or the key's permissions (or its user's profile) do not allow the action. The message says which. |
429 | More than 600 requests in 60 seconds with this key; slow down and retry. |