Scopes
The four token scopes and what each one allows.
On this page
Each endpoint needs one scope, named on its reference page. No scope includes another: a token that reads and writes holds both read and write.
The four scopes
| Scope | Allows | Example |
|---|---|---|
read | See your clusters, sites, environments, logs, usage and files. Changes nothing. | GET / |
write | Create and change sites, environments and settings, and remove what is configured on them, such as an environment variable. No commands. | POST / |
exec | Run commands and reveal stored secrets. | POST / |
destructive | Delete clusters, sites, environments and snapshots, or overwrite production. | DELETE / |
write includes removing configuration: a DELETE of an SSH key, a firewall entry, an environment variable, a repository connection or a team member needs write, not destructive.
destructive protects only the deletion of a CoreCluster, a site, an environment or a snapshot, and the overwrites of production listed under Requests that need a second scope. Each endpoint's reference page names the scope it needs.
Checks that save nothing need only read, even when they are a POST, such as POST /.
A missing scope
The scope is checked before anything is read or counted, so the answer is the same for an id that exists and one that does not, and a refused request spends no rate limit.
{
"message": "This access token does not have the write scope this needs. Use a token with the write scope.",
"reason": "scope_required",
"code": "scope_required",
"scope": "write"
}Requests that need a second scope
Some requests need a further scope, always or depending on what they ask for. The refusal is the same scope_required body, naming the further scope, and each endpoint's reference page lists its own.
| Request | Also needs | When |
|---|---|---|
POST / | destructive | The failed operation is a site delete, an environment delete or a copy onto production |
POST / | deploy | Always |
POST / | deploy | Always |
POST / | deploy | Always |
POST / | deploy | Always |
POST / | deploy | Always |
POST / | exec | The body asks for a generated password (password is generate) |
PATCH / | exec | The body asks for a generated password (password is generate) |
POST /corestack/sites | exec | To be shown the generated HTTP authentication passwords in credentials. Without it the create still succeeds and each password is null |
POST / | exec | To be shown the generated HTTP authentication password in credentials, when the request asks for http_auth. Without it the create still succeeds and the password is null |
POST /corestack/sites/{site}/clone | destructive | The copy goes onto production (target.type is production) |
POST /corestack/sites/{site}/clone | exec | copy_node_runtime is true and the source's Node.js packages run install scripts the target does not run now |
POST / | exec | A target environment gains a command it does not run now (never for a dry run) |
PUT / | exec | The save brings a command the saved stage does not hold (never for a dry run) |
POST / | exec | The pipeline gains a command it does not run now |
POST / | exec | An edit brings new text |
POST / | exec | The copied stages bring a command this pipeline does not run now (never for a dry run) |
PUT / | exec | The save brings a command the pipeline does not run now |
POST / | deploy | Always |
POST / | deploy | Always |
POST / | deploy | Always |
POST / | deploy | Always |
POST / | deploy | Always |
POST / | exec | To be shown the generated HTTP authentication password in credentials. Without it the create still succeeds and the password is null |
POST / | deploy | The environment is built from a git branch, which deploys that branch |
PUT / | exec | A user in the body asks for a generated password (generate is true) |
PUT / | exec | The packages turn install scripts on (scripts is true) for a package that does not run them on that site now |
POST / | exec | The copied packages turn install scripts on for a package that does not run them on a target now |
The deploy ability
Every request that starts, retries, stops, cancels, rolls back or rehearses a deployment, or uploads a release archive, needs deploy as well as its scope: the table above lists each one, and a token with write alone changes deployment settings and starts nothing. It is not one of the four scopes: it is a fifth tick, "Deploy", on Profile › API tokens, offered to a person whose role may deploy.
A token without it is refused like a missing scope, with "scope": "deploy".
{
"message": "This access token cannot deploy.",
"reason": "scope_required",
"code": "scope_required",
"scope": "deploy"
}Choosing scopes
| Use | Scopes |
|---|---|
| Dashboards and monitoring | read |
| Configuration scripts | read, write |
| Scripts that start, retry, stop or roll back deployments | read, write and the Deploy tick (deploy) |
| Scripts that run commands or read stored passwords | add exec |
| Jobs that delete clusters, sites, environments or snapshots, or overwrite production | add destructive |