Scopes Reference

API token scopes, what each one grants, and which endpoints require them.

A token's scopes are the first of the two authorization gates. 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.

Token, credit, and job-status utility endpoints do not require a data scope. Any valid token can read its own job status.

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.

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 — creating and using tokens.

• API Credits & Usage — how each endpoint type is metered.

• Error Reference — resolving 403 scope errors.