Scopes

Every fdk_ tenant credential carries a set of scopes. A scope names a capability (“manage this tenant’s webhooks”); the credential names WHICH tenant (the credential-carries-ownership pattern — see Authentication). A route resolves your tenant from the credential, never from a path or body parameter, and then checks that your credential holds the scope the route requires.

This page is the authoritative list. The set is a closed allowlist (TENANT_SCOPES in @dscodotco/stores): a key can only ever be issued with scopes from this list, and it is extended deliberately, one scope per merchant surface.

A route that requires a scope your credential lacks returns 403 with code forbidden and a message naming the missing scope. See Error codes.

How scopes are granted

Issuance is allowlist-checked. A key can only be minted with scopes in TENANT_SCOPES; an unknown scope is rejected at issuance.
Issuance is subset-gated. A key can never mint a key with scopes its own grant does not include (scopesAreSubset), so manage:own_credentials enables key management, never privilege escalation. A request for a scope the issuing key lacks fails 403 with code scope_escalation.
A verified owner self-mints the full current set. The store owner’s self-mint path issues a credential carrying the full current TENANT_SCOPES allowlist; the default credential the provisioning flow issues carries read:own_store and write:own_store.
Read/act are split deliberately. Where money or writes are involved, the read scope and the acting scope are separate (e.g. read:own_orders versus manage:own_orders), so a read-only integration key can never move money.

The naming convention

Prefix	Meaning
`read:own_*`	Read-only access to one of the tenant’s OWN resources.
`write:own_*`	Write access to one of the tenant’s OWN resources.
`manage:own_*`	Combined read-and-act on one of the tenant’s OWN resources (the surface has no use for a separate read-only key).

own is literal: a scope only ever grants access to the calling tenant’s own data, because the tenant is resolved from the credential.

Store and site

Scope	Grants	Required by
`read:own_store`	Read the tenant’s store, entitlements/add-on state, and partnerships. The default credential carries this.	Entitlements read routes; `GET /provenance/v1/my/partnerships`; provisioning read routes.
`write:own_store`	Enable/disable self-serve entitlements and file self-serve domain claims. The default credential carries this.	Entitlements enable/disable writes; provenance self-serve domain-claim write.
`manage:own_domains`	The whole self-serve custom-domain flow: request, list, verify-now, and remove a hostname claim.	The `/v1/my/domains` custom-domain routes (`@dscodotco/stores`). See Custom domains.

Orders and checkout

Scope	Grants	Required by
`read:own_orders`	List and read the tenant’s orders (with line items and refund records).	`GET /v1/merchant/orders`, `GET /v1/merchant/orders/:id`.
`manage:own_orders`	Act on the tenant’s own orders: full refund and pre-fulfillment cancel, driven through checkout’s shared settle/cancel executors (the same money path the operator routes use). Split from `read:own_orders` so a read-only key can never move money.	`POST /v1/merchant/orders/:id/refund`, `POST /v1/merchant/orders/:id/cancel`.
`manage:own_returns`	Read and act on the tenant’s returns/RMAs (approve/reject/receive).	The merchant returns routes (`@dscodotco/checkout`).

Catalog and pricing

Scope	Grants	Required by
`read:own_catalog`	Read the tenant’s commerce catalog.	`GET /v1/merchant/catalog`.
`manage:own_catalog`	Manage the tenant’s B2B/wholesale/VIP pricing groups: create groups, place customers in them, set per-variant integer-cents overrides. Distinct from the read-only `read:own_catalog` because these are writes to catalog pricing.	The merchant pricing-groups routes (`@dscodotco/commerce`).

Inventory and fulfillment

Scope	Grants	Required by
`manage:own_inventory`	Read and act on the tenant’s vendors, purchase orders, and receive-against-PO.	The merchant inventory routes (`@dscodotco/inventory`).
`manage:own_fulfillment`	Read and act on the tenant’s own fulfillment queue rows (allocate/label/ship/deliver). No separate read-only scope — a merchant with no act permission has no use for the queue.	The merchant fulfillment routes (`@dscodotco/fulfillment`).

Money surfaces

Scope	Grants	Required by
`manage:own_store_credit`	Read a customer’s store-credit balance/ledger and grant credit to them (tenant from the credential).	The merchant store-credit sub-app (`@dscodotco/cash`).
`manage:own_giftcards`	Issue and list the tenant’s gift cards.	The merchant gift-card routes (`@dscodotco/giftcards`).
`manage:own_subscriptions`	Read and act on the tenant’s subscriptions (cancel/pause/resume).	The merchant subscriptions routes (`@dscodotco/subscriptions`).
`read:own_billing`	Read the tenant’s own B2B invoices (platform fee, GMV fee, dropship COGS lines), invoice detail, and account statement. Read-only — merchants never issue/void their own invoices.	`GET /v1/merchant/billing/invoices`, `.../invoices/:id`, `.../billing/statement`.

Growth: webhooks, marketing, media, affiliates

Scope	Grants	Required by
`manage:own_webhooks`	Manage the tenant’s outbound webhook subscriptions and read the delivery ledger, including firing a test delivery.	`GET`/`POST`/`DELETE /v1/merchant/webhooks`, `POST /v1/merchant/webhooks/:id/test`, `GET /v1/merchant/deliveries`. See Webhooks.
`manage:own_marketing`	List/create the tenant’s own drip/broadcast campaigns and enroll their audience.	The merchant marketing routes (`@dscodotco/marketing`).
`manage:own_media`	List and upload the tenant’s own media assets.	The merchant media routes (`@dscodotco/media`). See Media.
`read:own_affiliates`	Read the tenant’s own affiliates, one affiliate’s commissions, and a program-level rollup.	The merchant affiliate read routes (`@dscodotco/affiliates`).
`manage:own_affiliates`	Self-approve a commission on the tenant’s own affiliate, which posts the balanced transaction to accounting (the same money path the operator route uses). Split from `read:own_affiliates` so a read-only key can never move money.	The merchant commission-approval route (`@dscodotco/affiliates`).

Fraud, analytics, customers

Scope	Grants	Required by
`manage:own_fraud`	Read and act on the tenant’s own ban blocklist.	The merchant fraud routes (`@dscodotco/fraud`).
`manage:own_analytics`	Read the tenant’s own revenue/orders, MRR, COGS margin, campaign performance, and search trends. Read-only rollups.	The merchant reporting routes (`@dscodotco/analytics`).
`read:own_customers`	Read the tenant’s own customer list (search + stats rollups), one customer’s profile/timeline, and the batch ref-to-name resolver. Read-only — no merchant may mutate a person row.	`GET /v1/merchant/customers`, `.../customers/resolve`, `.../customers/:id`.

Credential lifecycle

Scope	Grants	Required by
`manage:own_credentials`	List the tenant’s own API keys, issue new ones, and revoke them. Issuance is subset-gated, so this enables key management, never privilege escalation.	The merchant credential routes (`@dscodotco/stores`).

Count

There are 23 scopes in the closed TENANT_SCOPES allowlist: read:own_store, write:own_store, read:own_orders, read:own_catalog, manage:own_catalog, manage:own_webhooks, manage:own_domains, manage:own_fulfillment, manage:own_marketing, manage:own_media, manage:own_inventory, manage:own_fraud, manage:own_store_credit, manage:own_subscriptions, manage:own_giftcards, manage:own_returns, manage:own_orders, manage:own_analytics, read:own_billing, read:own_customers, read:own_affiliates, manage:own_affiliates, manage:own_credentials.

Authentication — how fdk_ credentials carry ownership.
Tenant-facing API — the routes and their per-route scopes.
Error codes — forbidden and scope_escalation.

Events Rate limits