---
title: "Scopes"
url: https://docs.corefinity.com/api/scopes
type: page
last_updated: 2026-11-13
feature: api
---
# Scopes

The four token scopes and what each one allows.

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 /corestack/sites/{site}/snapshots`                      |
| `write`       | Create 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`                     |
| `exec`        | Run commands and reveal stored secrets.                                                                                                  | `POST /corestack/sites/{site}/http-auth/users/{user}/reveal` |
| `destructive` | Delete 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](#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](/api/rate-limits).

```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.

| Request                                                                                  | Also needs    | When                                                                                                                                                                          |
| ---------------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /corestack/operations/{operation}/retry`                                           | `destructive` | The failed operation is a site delete, an environment delete or a copy onto production                                                                                        |
| `POST /environments/{environment}/deployments`                                           | `deploy`      | Always                                                                                                                                                                        |
| `POST /environments/{environment}/deployments/{deployment}/cancel`                       | `deploy`      | Always                                                                                                                                                                        |
| `POST /environments/{environment}/deployments/{deployment}/retry`                        | `deploy`      | Always                                                                                                                                                                        |
| `POST /environments/{environment}/deployments/{deployment}/rollback`                     | `deploy`      | Always                                                                                                                                                                        |
| `POST /environments/{environment}/deployments/{deployment}/run`                          | `deploy`      | Always                                                                                                                                                                        |
| `POST /corestack/sites/{site}/access/users`                                              | `exec`        | The body asks for a generated password (`password` is `generate`)                                                                                                             |
| `PATCH /corestack/sites/{site}/access/users/{user}`                                      | `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 /corestack/clusters/{cluster}/sites`                                               | `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 /corestack/companies/{company}/deploy-templates/{platform}/usage/reset`            | `exec`        | A 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}` | `exec`        | The save brings a command the saved stage does not hold (never for a dry run)                                                                                                 |
| `POST /corestack/sites/{site}/deployments/pipeline/{binding}/template-reset`             | `exec`        | The pipeline gains a command it does not run now                                                                                                                              |
| `POST /corestack/sites/{site}/deployments/carried-over/accept`                           | `exec`        | An edit brings new text                                                                                                                                                       |
| `POST /corestack/sites/{site}/deployments/pipeline/{binding}/copy`                       | `exec`        | The 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}`              | `exec`        | The save brings a command the pipeline does not run now                                                                                                                       |
| `POST /corestack/sites/{site}/deployments/rehearsals`                                    | `deploy`      | Always                                                                                                                                                                        |
| `POST /corestack/sites/{site}/deployments`                                               | `deploy`      | Always                                                                                                                                                                        |
| `POST /corestack/sites/{site}/deployments/{deployment}/retry`                            | `deploy`      | Always                                                                                                                                                                        |
| `POST /corestack/sites/{site}/deployments/{deployment}/rollback`                         | `deploy`      | Always                                                                                                                                                                        |
| `POST /corestack/sites/{site}/deployments/{deployment}/stop`                             | `deploy`      | Always                                                                                                                                                                        |
| `POST /corestack/sites/{site}/environments`                                              | `exec`        | To be shown the generated HTTP authentication password in `credentials`. Without it the create still succeeds and the password is null                                        |
| `POST /corestack/sites/{site}/environments`                                              | `deploy`      | The environment is built from a git branch, which deploys that branch                                                                                                         |
| `PUT /corestack/sites/{site}/http-auth`                                                  | `exec`        | A user in the body asks for a generated password (`generate` is true)                                                                                                         |
| `PUT /corestack/sites/{site}/node-runtime`                                               | `exec`        | The 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-to`                                     | `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"`.

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