api key scopes
api keys can be limited by scope so an integration gets only the permissions it needs. agents should request the smallest set of scopes that completes the job.
quick answer
use narrow scopes for each integration instead of one all-powerful key everywhere.
use this for
- choosing scopes for an ai assistant
- debugging a forbidden api response
- reviewing whether an integration can read or write documents
steps
- decide what the integration must do.
- create or edit the key with only those scopes.
- test the exact endpoint the integration needs.
- add a scope only when a real request fails because it is missing.
details to know
- `analyze` allows voice analysis calls.
- `rewrite` allows rewrite calls.
- `profiles:read` allows profile listing and profile resolution.
- `profiles:write` is reserved for profile-changing workflows.
- `documents:read` and `documents:write` control document sync.
- `usage:read` allows quota and usage inspection.
limits and edge cases
- missing scope normally means the key is valid but not allowed to perform that action.
- write scopes should not be given to read-only agents.
- scope names are api contracts and should not be renamed casually.
ready to use the product instead of reading about it?
open app