Keys and scopes
What each scope allows, how to rotate a key, and how to keep it safe.
An API key lets a server call the API for one organization. A key acts as the member who made it, with the role that member holds now: a member who leaves, or loses a role, takes the key's power with them.
Scopes
| Scope | Allows |
|---|---|
items:read | List and read items and their files. |
items:write | Create, edit, delete items and attach files. |
mcp | Use the MCP server with this key, for an agent that cannot sign in through OAuth. |
A key needs at least one scope. An endpoint refuses a key that lacks its scope with 403 Forbidden.
Create a key
Open API keys in the dashboard. Pick a name, the scopes and an expiry date or none. The key is shown once, as acme_live_.... We keep a digest of it, not the key: if you lose it, create a new one.
Rotate a key
Rotate makes a new key with the same scopes and expiry. The old key can keep working for a grace period (up to a few hours) so you can deploy the new one first.
Revoke a key
Revoke stops a key within seconds. It cannot be undone.
Keep a key safe
- Keep it in an environment variable on a server. Never put it in a browser, a mobile app or a repository.
- The
acme_live_prefix lets secret scanners recognize a leaked key. Revoke a leaked key at once. - Give each server its own key, with the fewest scopes it needs, so you can revoke one without stopping the others.
- The key's activity in the dashboard shows when it was last used.