How scopes work
Scope names follow aresource:action format (e.g. devices:read).
Nearly all API endpoints require one or more scopes, shown on the endpoint’s API Reference page. If an API key is missing a required scope, the request returns 403 Forbidden.
Scope tiers
Most resources follow a common tier pattern:| Tier | Access |
|---|---|
read | Get or list operations |
write | Create or update operations |
manage | All operations—superset of all other scopes for the resource |
write scope does not include read access—if you need both, select both scopes.
Some resources have additional granular scopes beyond the standard tiers (e.g. deployments:stage). The manage scope always includes everything for the resource.
Scopes by resource
Config instances
| Scope | Permissions |
|---|---|
config_instances:read | get, list |
config_instances:write | create |
config_instances:manage | all operations |
Config schemas
| Scope | Permissions |
|---|---|
config_schemas:read | get, list |
config_schemas:write | create, update |
config_schemas:manage | all operations |
Config types
| Scope | Permissions |
|---|---|
config_types:read | get, list |
config_types:write | create, update |
config_types:manage | all operations |
Deployments
| Scope | Permissions |
|---|---|
deployments:read | get, list |
deployments:write | create |
deployments:stage | stage |
deployments:deploy | deploy |
deployments:archive | archive |
deployments:manage | all operations |
Devices
| Scope | Permissions |
|---|---|
devices:read | get, list, ping |
devices:provision | create, activate, reactivate, list |
devices:write | create, update |
devices:delete | delete |
devices:manage | all operations |
Git commits
| Scope | Permissions |
|---|---|
git_commits:read | get, list |
git_commits:write | create |
git_commits:manage | all operations |
Releases
| Scope | Permissions |
|---|---|
releases:read | get, list |
releases:write | create, update |
releases:manage | all operations |