Skip to content

Scopes

Every scope a token may hold, and the operations each one allows.

Updated

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.

ScopeOperations
affiliate:readGET /affiliate_payouts, GET /commissions, GET /commissions/stats, GET /affiliates
affiliate:writePOST /affiliate_payouts, PUT /discounts/{discount}/affiliates, POST /discounts/{discount}/affiliates/remove, POST /discounts/{discount}/affiliates/revert
automation:readGET /automations, GET /automation_runs, GET /automations/{automation}
automation:writePOST /automations, PATCH /automations/{automation}, POST /automations/{automation}/pause, POST /automations/{automation}/resume
automation:deleteDELETE /automations/{automation}
certificate:readGET /certificates, GET /certificate_issues, GET /products/{product}/certificates/stats
certificate:writePOST /certificates/{certificate}/issue, POST /products/{product}/certificates, PATCH /certificates/{certificate}, POST /certificate_issues/{issue}/revoke
certificate:deleteDELETE /certificates/{certificate}
custompage:readGET /pages, GET /pages/{page}
custompage:writePOST /pages, PATCH /pages/{page}, POST /pages/{page}/publish, POST /pages/{page}/unpublish
custompage:deleteDELETE /pages/{page}
customer:readGET /customers/stats, GET /grants, GET /entitlements, GET /customers, GET /customer_activity, GET /products/{product}/customers, GET /products/{product}/customers/stats, GET /checkouts, GET /customers/{customer}
customer:writePOST /grants, POST /grants/{grant}/revoke
customer:deletePOST /customers/{customer}/erase
discount:readGET /discounts, GET /discounts/{discount}, GET /discounts/stats
discount:writePOST /discounts, PATCH /discounts/{discount}, POST /discounts/{discount}/archive, POST /discounts/{discount}/restore, POST /discounts/{discount}/restrict, POST /discounts/{discount}/attach, POST /discounts/{discount}/detach
discount:deleteDELETE /discounts/{discount}
file:readGET /{kind}/{id}/attachments, GET /body_schema, GET /{kind}/{id}/body, GET /products/{product}/prompts, GET /prompts/{prompt}, GET /assets, GET /assets/{asset}, GET /quota, GET /assets/{asset}/outputs, GET /assets/{asset}/output, POST /assets/{asset}/url, GET /products/{product}/file_stats, GET /asset_deliveries, GET /asset_uses, GET /files/{capability}
file:writePOST /{kind}/{id}/attachments, PUT /{kind}/{id}/body, POST /{kind}/{id}/body/edit, POST /{kind}/{id}/body/publish, POST /{kind}/{id}/body/discard, PATCH /attachments/{attachment}, POST /{kind}/{id}/attachments/reorder, POST /attachments/{attachment}/detach, POST /products/{product}/prompts, PATCH /prompts/{prompt}, PUT /products/{product}/poster, POST /assets, PATCH /assets/{asset}, PATCH /assets/{asset}/output, POST /assets/{asset}/outputs/generate, POST /assets/{asset}/outputs/publish, POST /uploads, POST /uploads/inline, POST /assets/{asset}/complete, POST /assets/{asset}/cancel, POST /assets/{asset}/move, POST /assets/{asset}/replace
file:deleteDELETE /prompts/{prompt}, DELETE /assets/{asset}, DELETE /assets/{asset}/output
integration:readGET /integrations
integration:writePUT /integrations/{integration}
organization:readGET /organization, GET /balance, GET /payouts, POST /plan_store/preview/query, GET /notifications, GET /webhooks, GET /webhooks/{webhook}, GET /webhook_deliveries, GET /v1/merchants, GET /v1/merchants/{merchant}
organization:writePATCH /organization, PUT /organization/logo, PUT /organization/auto_upgrade, PUT /organization/auto_add_ons, POST /notifications, PATCH /notifications/{notification}, POST /webhooks, PATCH /webhooks/{webhook}, POST /webhooks/{webhook}/secret/roll, POST /webhook_deliveries/{delivery}/resend
organization:deleteDELETE /notifications/{notification}, DELETE /webhooks/{webhook}
portfolio:readGET /products/{product}/portfolio, GET /products/{product}/portfolio_valuation, GET /products/{product}/portfolio_holdings, GET /portfolio_holdings/{holding}/announced_files, GET /products/{product}/portfolio_events, GET /products/{product}/portfolio_snapshots, GET /symbols, POST /symbols/quotes/query
portfolio:writePATCH /products/{product}/portfolio, PATCH /portfolio_holdings/{holding}, POST /products/{product}/portfolio_events
price:readGET /prices
price:writePOST /products/{product}/prices, PATCH /prices/{price}, POST /prices/{price}/highlight, POST /prices/{price}/archive, POST /prices/{price}/restore
price:deleteDELETE /prices/{price}
product:readGET /categories, GET /products, GET /products/{product}, GET /products/summaries, GET /tiers, GET /{kind}/{id}/access_requirements, POST /access_requirements/query, GET /products/{product}/stats, GET /products/stats
product:writePOST /products, PATCH /products/{product}, POST /products/{product}/publish, POST /products/{product}/unpublish, POST /products/{product}/discontinue, POST /products/{product}/reinstate, POST /products/{product}/unlist, POST /products/{product}/relist, POST /products/{product}/tiers, PATCH /tiers/{tier}, POST /products/{product}/tiers/reorder, PUT /{kind}/{id}/access_requirements, DELETE /{kind}/{id}/access_requirements
product:deleteDELETE /products/{product}, DELETE /tiers/{tier}
quiz:readGET /attempts, GET /attempts/{attempt}, GET /entries/{entry}/quizzes, GET /quizzes/{quiz}, GET /products/{product}/quizzes/stats
quiz:writePOST /entries/{entry}/quizzes, PATCH /quizzes/{quiz}
quiz:deleteDELETE /attempts/{attempt}, DELETE /quizzes/{quiz}, POST /entries/{entry}/attempts/clear
review:readGET /reviews, GET /reviews/stats
review:writePOST /reviews/{review}/reply
review:moderatePOST /reviews/{review}/hide, POST /reviews/{review}/unhide
site:readGET /v1/stores/{store}, GET /settings, GET /plan_usage, GET /domain, GET /redirects, GET /paths/check
site:writePATCH /v1/stores/{store}, PATCH /settings, POST /domain/connect, POST /domain/check, POST /domain/remove, PUT /icon, POST /redirects, PATCH /redirects/{redirect}
site:deleteDELETE /redirects/{redirect}
subpage:readGET /products/{product}/entries, GET /products/{product}/entries/details, GET /entries/{entry}, GET /products/{product}/entries/stats, GET /products/{product}/sections
subpage:writePOST /products/{product}/entries, PATCH /entries/{entry}, POST /entries/{entry}/publish, POST /entries/{entry}/unpublish, POST /products/{product}/entries/reorder, POST /products/{product}/sections, POST /products/{product}/sections/rename, POST /products/{product}/sections/remove
subpage:deleteDELETE /entries/{entry}
subscription:readGET /subscriptions/stats, GET /subscriptions, GET /subscription_periods, GET /subscription_transitions, GET /subscriptions/{subscription}
subscription:writePOST /subscriptions/{subscription}/cancel, POST /subscriptions/{subscription}/resume
transaction:readGET /stats, GET /orders/stats, GET /totals, GET /orders, GET /orders/{order}, GET /orders/{order}/items, GET /orders/{order}/settlements, GET /orders/{order}/refunds, GET /orders/{order}/affiliates
transaction:writePOST /orders, POST /orders/{order}/refunds

Operations that need more

  • Bulk. POST /bulk names no scope of its own: it needs the scope of the operation it runs, product:write to 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, read to read and write to change: product, subpage (entries), custompage (pages), quiz, certificate, portfolio (holdings) or site (the store). Attaching a file to an entry needs file:write and subpage: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:read to read prompts, product:write to 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:write and 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.

Type to search…

↑↓ navigate↵ selectEsc close