A scope names one thing a token may do, as resource:verb: product:read reads products, product:write changes them, product:delete deletes them. A token holds either every scope its seller’s seat holds (Everything I can do) or the ones chosen when it was created, and a call needs both the token and the seat to hold the operation’s scope. Without it the call answers 403 with WWW-Authenticate: Bearer error="insufficient_scope".
Most resources read as their names do. A few don’t: entry covers every entry (lessons, posts and episodes) and their sections, pages are custompage, the store’s site and settings are site, orders and refunds are transaction, a product’s portfolio is portfolio, and the business itself is organization.
Each operation’s page in the reference names its scope. This table lists every scope a public operation needs, with those operations; it is generated from the API on every build.
Operations that need more
- Bulk.
POST /bulknames no scope of its own: it needs the scope of the operation it runs,product:writeto publish products, checked before any item runs. See bulk changes. - Attachments and bodies. What hangs on a product, an entry, a page, a quiz, a certificate, a holding or the store needs the file scope the operation names and also that target’s own scope,
readto read andwriteto change:product,entry,custompage(pages),quiz,certificate,portfolio(holdings) orsite(the store). Attaching a file to an entry needsfile:writeandentry:write. - Prompts and thumbnails. A product’s prompts and its thumbnail need the file scope the operation names and the product’s own too:
product:readto read prompts,product:writeto change them or the thumbnail. Their pages in the reference name both scopes. - Webhooks. Creating an endpoint, adding events to it, resending a delivery or rolling its secret needs
organization:writeand the read scopes of the events’ payloads, since what they send is read with your access. The webhooks page lists each event’s. - Simulating an order.
GET /products/{product}/checkout/simulateneedsprice:read, pluscustomer:readto name a customer anddiscount:readto name a coupon. See simulate an order.
Scopes that change what you see
revenue:read is no operation’s scope, but money follows it: without it, takings and fees come back as null wherever they appear (an order’s amounts and lines, refunds, commissions, a product’s or the store’s stats), and sorting orders by amount or fees answers 403 with the reason scope, since the order would give the amounts away. Give it to a token that needs to see money.
Without discount:read, a simulated order still shows what its automatic discount takes off, but the discount’s id, name and code come back as null.
Scopes the API doesn’t use
The apitoken, client, member and user scopes cover what only the merchant app does: API tokens, store API clients, the business’s members and your own profile. An account token may hold them, since Everything I can do follows your seat, but they give it nothing on this API; a business token never holds the apitoken scopes.