Scopes

Use this page to understand the management scope model and common least-privilege bundles.

Who This Is For

operators creating scoped API keys
SDK and automation authors
developers debugging TOKEN_SCOPE_DENIED

When To Use This

Read this page before designing management tokens or when reviewing route permissions.

How It Works

Current management scopes:

admin
product:read
product:write
license:read
license:write
device:write
event:read
ops:read
report:read
report:export
webhook:write

Rules:

admin satisfies every management operation
operation-level x-required-scopes in OpenAPI is the least-privilege source of truth
runtime routes do not use these scopes; they use Authorization: License <license-key>

Common bundles:

catalog setup: product:write
license issuance and lifecycle: license:write
device inspection plus reads: license:read
device reset and blacklist: device:write
raw audit feed: event:read
ops rollups: ops:read
reporting reads: report:read
reporting exports: report:export
webhook configuration: webhook:write

Example

text

operationId: createReportExport
x-required-scopes: ["report:export"]

text

operationId: listEvents
x-required-scopes: ["event:read"]

Common Mistakes

using admin for all automation by default
inferring route scope from the HTTP method alone
forgetting that webhook reads currently still require webhook:write