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: 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.

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
attendee:checkinPOST /products/{product}/attendees/check_in, DELETE /products/{product}/attendees/{attendee}/check_in, GET /products/{product}/attendees/check_in/stats, GET /products/check_in
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 /products/{product}/certificates, GET /certificates/issues, GET /products/{product}/certificates/issues, GET /products/{product}/certificates/stats
certificate:writePOST /products/{product}/certificates, POST /products/{product}/certificates/{certificate}/issue, PATCH /products/{product}/certificates/{certificate}, POST /products/{product}/certificates/issues/{issue}/revoke
certificate:deleteDELETE /products/{product}/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 /feeds, GET /products/{product}/feeds, GET /products/{product}/licenses, GET /products/{product}/licenses/{license}, GET /products/{product}/licenses/stats, GET /products/{product}/licenses/{license}/activations, POST /products/{product}/licenses/verify, POST /products/{product}/licenses/token, GET /license_signing_keys, GET /entitlements, GET /customers, GET /customer_activity, GET /products/{product}/customers, GET /products/{product}/customers/stats, GET /checkouts, GET /customers/{customer}, GET /products/{product}/attendees, GET /products/{product}/attendees/stats, GET /customers/{customer}/answers, GET /products/{product}/requests
customer:writePOST /grants, POST /grants/{grant}/revoke, PATCH /products/{product}/feeds/{feed}, POST /products/{product}/feeds/{feed}/revoke, POST /products/{product}/feeds/unblock, POST /products/{product}/licenses, PATCH /products/{product}/licenses/{license}, POST /products/{product}/licenses/{license}/disable, POST /products/{product}/licenses/{license}/enable, POST /products/{product}/licenses/{license}/activations/{activation}/deactivate, POST /products/{product}/licenses/{license}/rotate, POST /products/{product}/licenses/activate, POST /products/{product}/licenses/deactivate, POST /license_signing_keys/rotate, PUT /products/{product}/customers/{customer}/answers, POST /products/{product}/requests/{request}/approve, POST /products/{product}/requests/{request}/decline, POST /products/{product}/requests/{request}/promote
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}
entry:readGET /products/{product}/entries, GET /products/{product}/entries/details, GET /products/{product}/entries/{entry}, GET /products/{product}/entries/stats, GET /products/{product}/entries/sections, GET /products/{product}/entries/tags, GET /products/{product}/sections
entry:writePOST /products/{product}/entries, PATCH /products/{product}/entries/{entry}, POST /products/{product}/entries/{entry}/publish, POST /products/{product}/entries/{entry}/unpublish, POST /products/{product}/entries/reorder, POST /products/{product}/sections, POST /products/{product}/sections/rename, POST /products/{product}/sections/remove
entry:deleteDELETE /products/{product}/entries/{entry}
file:readGET /{kind}/{id}/attachments, GET /body_schema, GET /{kind}/{id}/body, GET /products/{product}/prompts, GET /products/{product}/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 /products/{product}/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 /products/{product}/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 /organization/plan/change/preview, GET /notifications, GET /webhooks, GET /webhooks/{webhook}, GET /webhook_deliveries, GET /v1/merchants, GET /v1/merchants/{merchant}
organization:writePATCH /organization, PUT /organization/logo, POST /organization/plan/change, DELETE /organization/plan/change, POST /organization/plan/change/confirm, 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 /products/{product}/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 /products/{product}/portfolio/holdings/{holding}, POST /products/{product}/portfolio/events
price:readGET /prices, GET /products/{product}/prices, GET /products/{product}/checkout/simulate
price:writePOST /products/{product}/prices, PATCH /products/{product}/prices/{price}, POST /products/{product}/prices/{price}/highlight, POST /products/{product}/prices/{price}/archive, POST /products/{product}/prices/{price}/restore
price:deleteDELETE /products/{product}/prices/{price}
product:readGET /categories, GET /products, GET /products/{product}, GET /products/summaries, GET /tiers, GET /products/{product}/tiers, GET /{kind}/{id}/access_requirements, POST /access_requirements/query, GET /products/{product}/stats, GET /products/stats, GET /products/{product}/traffic/stats, GET /products/{product}/questions, GET /products/{product}/sessions, GET /products/{product}/cancellation, GET /products/{product}/activity
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 /products/{product}/tiers/{tier}, POST /products/{product}/tiers/reorder, PUT /{kind}/{id}/access_requirements, DELETE /{kind}/{id}/access_requirements, POST /products/{product}/questions, PATCH /products/{product}/questions/{question}, POST /products/{product}/sessions, PATCH /products/{product}/sessions/{session}, POST /products/{product}/activity, PATCH /products/{product}/activity/{event}
product:deleteDELETE /products/{product}, DELETE /products/{product}/tiers/{tier}, DELETE /products/{product}/questions/{question}, DELETE /products/{product}/sessions/{session}, DELETE /products/{product}/activity/{event}
quiz:readGET /attempts, GET /products/{product}/attempts, GET /products/{product}/attempts/{attempt}, GET /products/{product}/entries/{entry}/quizzes, GET /products/{product}/entries/{entry}/quizzes/{quiz}, GET /products/{product}/quizzes/stats
quiz:writePOST /products/{product}/entries/{entry}/quizzes, PATCH /products/{product}/entries/{entry}/quizzes/{quiz}
quiz:deleteDELETE /products/{product}/attempts/{attempt}, DELETE /products/{product}/entries/{entry}/quizzes/{quiz}, POST /products/{product}/entries/{entry}/attempts/clear
review:readGET /reviews, GET /products/{product}/reviews, GET /reviews/stats, GET /products/{product}/reviews/stats
review:writePOST /products/{product}/reviews/{review}/reply
review:moderatePOST /products/{product}/reviews/{review}/hide, POST /products/{product}/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}
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 /traffic/stats, GET /conversion/stats, GET /calls/stats, GET /orders, GET /orders/{order}, GET /orders/{order}/items, GET /orders/{order}/settlements, GET /orders/{order}/refunds, GET /orders/{order}/affiliates, GET /revocations, GET /products/{product}/event_refunds
transaction:writePOST /orders, POST /orders/{order}/refunds, POST /revocations, POST /revocations/{revocation}/refund/retry, POST /products/{product}/cancel, POST /event_refunds/{refund}/retry

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, entry, custompage (pages), quiz, certificate, portfolio (holdings) or site (the store). Attaching a file to an entry needs file:write and entry: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.
  • Simulating an order. GET /products/{product}/checkout/simulate needs price:read, plus customer:read to name a customer and discount:read to 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.

Type to search…

↑↓ navigate↵ selectEsc close