> For the complete documentation index, see [llms.txt](https://docs.claret.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.claret.app/api-guide/scopes.md).

# Scopes Reference

A token's **scopes** are the first of the [two authorization gates](/api-guide/authentication.md#two-gate-authorization). Each scope grants a coarse category of access. Select the narrowest set of scopes an integration needs; you can always create a second token for a different job.

## Available scopes

The **API Access** UI presents friendly labels. Each maps to an internal scope string that appears in audit logs and the OpenAPI spec.

| UI label         | Internal scope                | Grants                                                                                 |
| ---------------- | ----------------------------- | -------------------------------------------------------------------------------------- |
| Read             | `public_api.read`             | Read-only access to all `GET` data endpoints (reference and transactional).            |
| Write            | `public_api.write`            | Create and update records on write endpoints.                                          |
| Compute          | `public_api.compute`          | Run compute endpoints (supply plan generation, forecasts).                             |
| Workflow Sync    | `public_api.workflow`         | Trigger workflow sync endpoints (inventory, sales).                                    |
| Workflow Replace | `public_api.workflow.replace` | Required in addition to Workflow Sync to use `replace` mode, which can delete records. |
| All Permissions  | `*`                           | Full access to every endpoint. Use sparingly.                                          |

{% hint style="info" %}
Token, credit, and job-status utility endpoints do not require a data scope. Any valid token can read its own job status.
{% endhint %}

## Scope required per endpoint type

| Endpoint type                | Example                                                        | Required scope                                              |
| ---------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------- |
| Reference data (read)        | `GET /items`, `GET /uoms`, `GET /calendars`                    | `public_api.read`                                           |
| Transactional data (read)    | `GET /sales-data`, `GET /inventory`, `GET /supply-plans`       | `public_api.read`                                           |
| Compute                      | `POST /supply-plans/generate`, `POST /forecasts/generate`      | `public_api.compute`                                        |
| Workflow sync (upsert)       | `POST /workflows/sync-inventory`, `POST /workflows/sync-sales` | `public_api.workflow`                                       |
| Workflow sync (replace mode) | `POST /workflows/sync-inventory` with `"mode": "replace"`      | `public_api.workflow` **and** `public_api.workflow.replace` |

A request that reaches an endpoint without the required scope returns `403`. See the [Error Reference](/api-guide/errors.md).

## Who can mint which scopes

Creating a token requires a Claret seat with the matching access level:

* **Read** (`public_api.read`) can be created by any user with access to the API Access page.
* **Write**, **Compute**, **Workflow Sync**, **Workflow Replace**, and **All Permissions** require **Planner ("Full Access")** access to the Public API module, or Workspace Admin.

If a user without Planner access tries to create a token carrying a privileged scope, the request is rejected with `403` before the token is minted. The Create Token modal only offers scopes the current user is allowed to mint.

## Related documentation

* [Authentication & Tokens](/api-guide/authentication.md) — creating and using tokens.
* [API Credits & Usage](/api-guide/credits-and-usage.md) — how each endpoint type is metered.
* [Error Reference](/api-guide/errors.md) — resolving `403` scope errors.