Scopes
A scope is a permission your access token carries. On v2, a scoped service checks for its
one scope on every call and answers 403 without it. v1 checks each route against the
scopes that admit it.
Two rules decide whether a call goes through, on v1 and v2 alike:
- The token’s scopes are what count. The scope list on your registered application is not consulted at call time. Only the scopes minted into the token are.
- Holding any one of a route’s scopes is enough. A route lists the scopes that admit it, and one match authorizes the call. It is any of, not all of.
The scopes
Section titled “The scopes”Each row is one scope in the registry, with the routes this portal publishes for it.
| Scope | What it opens | Published routes |
|---|---|---|
legacy | Access to all "legacy" endpoints for all integrations. | 20 routes
|
deliverr | Access to the custom Deliverr integration endpoints. | No published route |
inventory | Full access to inventory endpoints for all warehouses. | 6 routes
|
inventory:self | Can only see warehouses that use the integration in the SC. And only inventory in those warehouses will be returned or able to be modified. | 10 routes
|
inventory:warehouse | Access to all warehouses | 2 routes
|
inventory:warehouse:self | Access to all warehouses that use the integration in the SC. | 3 routes
|
listing | Reserved for the future | No published route |
listing:self | Can retrieve listings and submit listing status and submissions for the integration in the SC. | 6 routes
|
sales | Full access to sales orders for all integrations. | 8 routes
|
sales:orders | Currently the same as `sales` but reserved to allow that to expand to other sales endpoints. | 8 routes
|
sales:orders:self | Can retrieve, create, update sales orders for the integration in the SC | 8 routes
|
sales:orders:fulfillment:self | Includes Address information in each Sales Order | 16 routes
|
sales:orders:inventory:self | Read-only: can retrieve sales orders for the integration in the SC. No create or update access. | 3 routes
|
scm | Full access to scm endpoints: inbound shipments, purchase orders, vendors, and warehouses. | 3 routes
|
scm:purchase_orders | Access to purchase orders. | No published route |
scm:inbound_shipments | Access to inbound shipments. | No published route |
report | Full access to reports. | 5 routes
|
ui | Internal scope for the Zentail web app, not for third-party integrations. Covers import validation, inbound shipments, purchase orders, vendors, and warehouses. | 5 routes
|
mcpUndocumented | Undocumented. This scope is in the registry but the authentication reference does not describe it. | No published route |
"No published route" does not always mean "does nothing". Five scopes — deliverr, listing, scm:purchase_orders, scm:inbound_shipments and mcp — open no route in the APIs published here. Some cover endpoints outside this portal; others are reserved and unused. Either way, holding one buys you nothing on the routes above.
Where a scope’s description and its routes disagree, trust the routes. The descriptions
come from an internal reference, and it can lag: some scopes — mcp and ui — carry no
description at all. The route column is generated from the same specification the API
reference is built from, so it moves when the API does.
Decide from that column before you register, not after. Your application’s scopes are fixed at registration (below). Adding one later is possible, but it does not reach any seller who has already installed your application — so a scope skipped on the strength of a stale description has to be chased down install by install.
Undocumented scopes
Section titled “Undocumented scopes”mcp is in the registry and marked Undocumented above. A token can hold it, but the authentication reference does not say what it grants.
Your scopes are fixed when your application is registered
Section titled “Your scopes are fixed when your application is registered”Your application’s scopes are set during registration. The
authorization request has no scope parameter you
can influence — a scope value sent with it is ignored, and every token minted for your
application carries the set that was registered.
A scope added to your application later does not reach sellers who have already installed it. Installing writes the application’s scope set onto the integration once, when the integration is created. A seller reauthorizing an existing integration reactivates it without rewriting that set, so their token keeps the scopes it was minted with.
Which services enforce scopes
Section titled “Which services enforce scopes”A scoped service checks one scope for the whole service, not one per operation. The
inventory integration service and the fulfillment integration service each build one
authorizer for the whole service, so every operation on that service carries the one scope
the authorizer enforces: inventory:self for the 4 inventory operations,
sales:orders:fulfillment:self for the 10 fulfillment operations.
The sales-channel /v2/storefront services are authenticated but not scope-gated, so the
reference shows no scope requirement against their operations. That is a fact about those services today,
not a rule for every service.
A call to a scoped service without its scope answers 403, and the message names the
missing scope. See Errors.
See also
Section titled “See also”- Zentail authentication flow — how a token, and therefore its scopes, is issued.
- Errors — the
403a missing scope answers.
API changelog · Built 0c509dd3