Every API key can help an integration do exactly what it needs and nothing more, but that only holds if you configure permissions deliberately, watch for signs of misuse, and know what to do when something looks wrong. This page covers the permission model, rate limiting, monitoring requests, and responding when a key is behaving badly.
How API key permissions work#
An API key isn't a separate access system: creating one builds an internal role and grants it exactly the permissions you selected, using the same permission model as a user Role. This means:
- A key can only be granted permissions its creator already holds. You can't use an API key to grant more access than your own account has.
- Permissions can be changed after creation, from the same Set Permissions view used when the key was created: you don't need to issue a new key to narrow or widen its access.
- Enable all permissions / Disable all permissions toggles the whole set at once, useful as a starting point before narrowing to specifics.
Keep every key scoped to what its integration actually does. A key with broader access than it uses is a bigger problem the moment it leaks.
Rate limiting#
Rate limiting is configured system-wide, not per key, using a token-bucket model with short bursts allowed. The default allows 50 requests per second; you can adjust this from the Rate limiting control in Settings → API, up to a maximum of 1000 requests per second, or turn limiting off entirely.
Each key is tracked against this limit independently: one key being rate-limited doesn't affect another. A request that exceeds the limit gets a 429 Too Many Requests response, along with rate-limit headers indicating when to retry.
Monitor activity#
The Control API Requests log shows every request made through the API in real time: client address, method, path, and status code for each one. This is the fastest way to notice something worth investigating: a burst of requests from an address you don't recognize, repeated failures against endpoints a key shouldn't be touching, or a spike right before something unexpected happened in Buttons.
A key's own detail view also shows Last used, useful for confirming whether a key is actually still in active use before you consider revoking it.
Respond to misuse#
- Open Control API Requests and confirm what the suspicious activity actually is: which key, which endpoints, from where.
- Open that key's detail view and select Revoke key. Revocation is immediate and can't be undone: every request using that key fails afterward with 401 Unauthorized.
- Issue a new, appropriately scoped key if the integration still needs access, rather than reusing the old value anywhere.
- If the exposure was broader than one key (for example, a shared machine or repository), review every key for unfamiliar activity, not just the one you already suspect.
If you get stuck#
What you see | What to try |
|---|
Legitimate requests are being rate-limited. | Raise Requests / sec in Settings → API, or split heavy integrations across more than one key so each stays under the limit independently. |
You can't tell which key is generating unexpected traffic. | Cross-reference the client address and path in Control API Requests against each key's own Last used timestamp and granted permissions. |
A key seems to have more access than intended. | Open Set Permissions on the key and remove anything beyond what its integration actually uses: this takes effect without reissuing the key. |
Where to go next#
