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: entries (lessons and articles) are subpage, 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,subpage(entries),custompage(pages),quiz,certificate,portfolio(holdings) orsite(the store). Attaching a file to an entry needsfile:writeandsubpage: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.
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.
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. A token may hold them, since Everything I can do follows your seat, but they give it nothing on this API.