CorefinityCorefinityDocs
Open the Control PanelControl Panel
Essentials · 3 of 12

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

ScopeAllowsExample
readSee your clusters, sites, environments, logs, usage and files. Changes nothing.GET /corestack/sites/{site}/snapshots
writeCreate and change sites, environments and settings, and remove what is configured on them, such as an environment variable. No commands.POST /corestack/sites/{site}/snapshots
execRun commands and reveal stored secrets.POST /corestack/sites/{site}/http-auth/users/{user}/reveal
destructiveDelete clusters, sites, environments and snapshots, or overwrite production.DELETE /corestack/snapshots/{snapshot}

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 /corestack/clusters/{cluster}/capacity/check.

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.

json
{
  "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.

RequestAlso needsWhen
POST /corestack/operations/{operation}/retrydestructiveThe failed operation is a site delete, an environment delete or a copy onto production
POST /environments/{environment}/deploymentsdeployAlways
POST /environments/{environment}/deployments/{deployment}/canceldeployAlways
POST /environments/{environment}/deployments/{deployment}/retrydeployAlways
POST /environments/{environment}/deployments/{deployment}/rollbackdeployAlways
POST /environments/{environment}/deployments/{deployment}/rundeployAlways
POST /corestack/sites/{site}/access/usersexecThe body asks for a generated password (password is generate)
PATCH /corestack/sites/{site}/access/users/{user}execThe body asks for a generated password (password is generate)
POST /corestack/sitesexecTo be shown the generated HTTP authentication passwords in credentials. Without it the create still succeeds and each password is null
POST /corestack/clusters/{cluster}/sitesexecTo 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}/clonedestructiveThe copy goes onto production (target.type is production)
POST /corestack/sites/{site}/cloneexeccopy_node_runtime is true and the source's Node.js packages run install scripts the target does not run now
POST /corestack/companies/{company}/deploy-templates/{platform}/usage/resetexecA target environment gains a command it does not run now (never for a dry run)
PUT /corestack/companies/{company}/deploy-templates/{platform}/{config}/stages/{stage}execThe save brings a command the saved stage does not hold (never for a dry run)
POST /corestack/sites/{site}/deployments/pipeline/{binding}/template-resetexecThe pipeline gains a command it does not run now
POST /corestack/sites/{site}/deployments/carried-over/acceptexecAn edit brings new text
POST /corestack/sites/{site}/deployments/pipeline/{binding}/copyexecThe copied stages bring a command this pipeline does not run now (never for a dry run)
PUT /corestack/sites/{site}/deployments/pipeline/{binding}/stages/{stage}execThe save brings a command the pipeline does not run now
POST /corestack/sites/{site}/deployments/rehearsalsdeployAlways
POST /corestack/sites/{site}/deploymentsdeployAlways
POST /corestack/sites/{site}/deployments/{deployment}/retrydeployAlways
POST /corestack/sites/{site}/deployments/{deployment}/rollbackdeployAlways
POST /corestack/sites/{site}/deployments/{deployment}/stopdeployAlways
POST /corestack/sites/{site}/environmentsexecTo be shown the generated HTTP authentication password in credentials. Without it the create still succeeds and the password is null
POST /corestack/sites/{site}/environmentsdeployThe environment is built from a git branch, which deploys that branch
PUT /corestack/sites/{site}/http-authexecA user in the body asks for a generated password (generate is true)
PUT /corestack/sites/{site}/node-runtimeexecThe packages turn install scripts on (scripts is true) for a package that does not run them on that site now
POST /corestack/sites/{site}/node-runtime/apply-toexecThe 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".

json
{
  "message": "This access token cannot deploy.",
  "reason": "scope_required",
  "code": "scope_required",
  "scope": "deploy"
}

Choosing scopes

UseScopes
Dashboards and monitoringread
Configuration scriptsread, write
Scripts that start, retry, stop or roll back deploymentsread, write and the Deploy tick (deploy)
Scripts that run commands or read stored passwordsadd exec
Jobs that delete clusters, sites, environments or snapshots, or overwrite productionadd destructive
Was this helpful?
Open in ClaudeOpen in ChatGPT