Scopes · security
Canonical scope reference
The ten registered scopes, their risk, real public coverage, and requestability and reviewed capability contracts.
Canonical scope reference
Scopes are app permissions, not human roles. A version requests them and a merchant Owner or Admin grants a subset at installation. The API still validates the active installation, tenant, exact version, token, and route-specific scope on every request.
Least privilege and merchant meaning
Ask only for a scope that maps to a documented operation your app uses. Show the merchant why each grant is needed and what data or action it covers. A high-risk label calls for stronger review; it does not make the capability operational.
Current registry truth
| Scope | Risk | Status | Actual public coverage and caveat |
|---|---|---|---|
catalog:read | low | CURRENT | GET /api/v1/catalog/products; products only, not category resources. |
catalog:write | high | PLANNED | Registered but disabled and not requestable; no public product or category write route. |
customers:read | high | CURRENT | GET /api/v1/customers; names, phone, email and creation time only. |
discounts:read | medium | CURRENT | GET /api/v1/discounts; currently active rules and codes; no redemptions. |
discounts:write | high | PLANNED | Registered but disabled and not requestable; no public discount mutation route. |
inventory:read | medium | CURRENT | GET /api/v1/inventory/locations, /levels, /movements; quantities and identifiers; no notes or staff. |
orders:read | high | CURRENT | GET /api/v1/orders; order summaries only, not a line-item contract. |
orders:write | high | PLANNED | Registered but disabled and not requestable; no public order mutation route. |
store:read | low | CURRENT | GET /api/v1/store; names, ID and subdomain; no private settings or bank details. |
webhooks:manage | medium | CURRENT | Manage subscriptions and receive only reviewed resource events under webhooks.events.v2. Private Staging delivery acceptance passed. |
Requestability and reviewed contracts
Seven scopes are requestable: catalog:read, customers:read, discounts:read, inventory:read, orders:read, store:read, and webhooks:manage. The three write scopes remain disabled. Each reviewed version captures the operational meaning of its scopes. A future expansion requires a new reviewed app version and fresh merchant consent; an old token cannot silently acquire the expanded permission. These scopes never authorize private database objects or undocumented endpoints.
Fail-closed handling
Treat 401 as a missing or invalid token and 403 as a denied operation where documented. Never retry by escalating scopes, changing tenant identifiers, spraying tokens, or falling back to an internal credential. Ask the merchant to approve a reviewed version when a legitimate new grant is needed.