API keys

What a key can do, where it should live, and how to rotate one without an outage.

An API key is a bearer token: whoever holds it is the organisation, for everything that key is allowed to do. That single sentence decides everything else on this page.

Where a key lives

• On a server you control, read from your own configuration or secret store.
• Never in a browser, a mobile app, a desktop app or anything else a user can open.
• Never in a repository, a build log, a screenshot or a support ticket.
• One key per integration, so a rotation affects one system and a leak has a known blast radius.

Rotating one

1. 1

   Create the new key

   In the console, under Settings. Two keys can be live at once, which is what makes this safe.

2. 2

   Deploy it

   Update your configuration and let the new key take traffic.

3. 3

   Delete the old one

   DELETE it in the console once nothing is using it. From that moment it answers 401.

If a key has leaked, do it in the opposite order: delete first and accept the short outage. An hour of failed requests costs less than an unknown party holding your organisation.

Or use tokens instead

For a long-running integration, POST /oauth/token with the client_credentials grant exchanges a client id and secret for a short-lived access token. The static secret stays in your configuration and never travels on a request, and a token that leaks expires on its own.