Authentication
Create a key in the app under Settings → API keys.
It is shown once and stored only as a hash. It cannot be recovered — losing it means issuing a new one.
Send it as either header:
What a key can do
Deliberately narrow. A key reads the endpoints in this reference and nothing else. It is not a session: it cannot create or delete projects, change settings, or issue another API key.
That last one matters — key management sits behind the normal signed-in session, so a leaked read-only key cannot mint itself a permanent one.
What a key can see
Exactly what its owner can see, re-checked on every request. No access list is copied onto the key, so:
- Removing someone’s access to a project removes it from their key on the very next call.
- Deactivating an account stops all of that person’s keys immediately.
Commit history additionally needs git visibility on the project — the same
separate permission that governs whether you can see git in the app. Project
access alone is not enough, and a project you can reach but whose git is not
enabled for you is simply omitted from /api/v1/projects rather than listed and
then refused.
Revoking
Revoke from the same screen. It takes effect on the next request. Keys are marked revoked rather than deleted, so the record of what existed survives the key.
lastUsedAt updates on every successful call, which makes an unused key easy to
spot and retire.