API Key Scopes Reference

Secret vs publishable keys

API keys come in two prefixes. Secret keys (sk_) are full-power, server-side credentials — keep them on your backend and never expose them. Publishable keys (pk_) are safe to embed in browser or frontend code. Because a publishable key is application-scoped and exposed in the browser, it is restricted to a small, curated set of publishable-allowed scopes — five today: shipping_quotes:write, tax_calculations:write, storefront_scripts:read, storefront_scripts:write, and customer_accounts:write — and can never read carts, orders, customers, payment methods, or PII directly. That last scope is a deliberate exception to "publishable means stateless compute"; see the buyer plane below. (Listing available payment methods needs no key: GET /v1/payment-methods is public.) Create either type from Developers → API keys in the dashboard.

How scope checks work

On every API-key request Throttle reads the matched route's required scope and checks it against the key's granted scopes using these rules:

Key types & grantable scopes

The buyer plane: a publishable key is not a permission

Every other publishable scope (shipping_quotes:write, tax_calculations:write, storefront_scripts:read, storefront_scripts:write) authorises a stateless compute or a public read directly off the key itself. customer_accounts:write works differently: holding it only unlocks the /v1/storefront/* route family (see Storefront Customer Auth ). Every action a buyer actually takes there — reading their orders, changing an address, removing a saved card — is authorised by their own Authorization: Bearer session token, never by the key. Two different applications' publishable keys can both hold customer_accounts:write and still never see each other's buyers; the key only decides which application a login or register request lands on.

Customer PII: redacted, not rejected

customer_pii:read gates personal fields on a customer record — email, phone, firstName, lastName, and the combined name some endpoints return. A credential that can read (or write) customers but lacks this scope does not get a 403: the request succeeds and those fields come back null, with every other field (id, externalId, company, addresses, order/subscription linkage) intact — the same "redact, not reject" pattern the picker warning on ⚠ sensitive exists to flag. This applies whether the customer came back from a read, or is the record echoed back by a create/update call. Because customer_pii:read is sensitive, an OAuth connection to an AI assistant (the MCP integration flow) can never hold it — see the MCP docs for which tools therefore always return redacted customer data. It is the one sensitive scope an automation connector (Zapier, Make — an OAuth client registered for the REST API) may be granted, and the consent screen names it. A connector without it gets the same redaction, and creating, changing or replaying a webhook endpoint returns 403 oauth_customer_pii_required, because deliveries carry the full record.

Storefront quote tokens: qt_

Shipping/tax quote tokens minted from Developers → Shipping & Tax → Tokens (or POST /api/v1/shipping-tax/quote-tokens) now start with qt_, not pk_. A quote token is a separate, narrower credential from a publishable API key — valid only for POST /api/v1/shipping-tax/quotes — even though older tokens were minted with a pk_ prefix before this split. Tokens minted before the change keep their pk_ prefix and remain valid indefinitely; the quote endpoint accepts either prefix. Presenting a qt_ token as X-API-Key on any other route returns 401 quote_token_not_api_key — a distinct code from the generic invalid-key error, naming the mix-up rather than leaving a merchant to guess why a token that works on the quotes endpoint fails everywhere else.

Scope catalog

Every scope, grouped as it appears in the dashboard picker. A scope marked ⚠ sensitive triggers a picker warning (financial, destructive, or PII); pk_ ok means a publishable key may hold it; staff only means it is unreachable by any workspace key. Unless a row lists both, the resource exposes only the action shown.

Migration from coarse scopes

Throttle previously used ~27 coarse scopes (for example a single payments:write). Those were replaced with the granular catalog above. Existing keys keep working unchanged:

• Each legacy scope expands to the superset of granular scopes it used to cover — so a key with the old payments:write now holds payment_authorizations:write, payment_captures:write, payment_refunds:write, and the rest of the payment family. No power is lost.
• stores:read and stores:write are deprecated aliases for applications:read / applications:write, still accepted on input and expanded at evaluation time. New keys should request applications:read / applications:write directly.

Machine-readable catalog

GET /api/v1/scopes returns the full catalog as JSON — every scope definition (id, resource, action, group, label, sensitive, staffOnly, publishableAllowed, extensionAllowed, implies) plus the group ordering. Build a scope picker or validate requested scopes against it rather than hard-coding the list.

        {
  "data": {
    "scopes": [
  {
    "id": "payment_refunds:write",
    "resource": "payment_refunds",
    "action": "write",
    "group": "Payments",
    "label": "Refund payments",
    "sensitive": true,
    "staffOnly": false,
    "publishableAllowed": false,
    "extensionAllowed": true,
    "implies": ["payment_refunds:read"]
  }
  // ...
    ],
    "groups": { "Payments": ["payments:read", "payments:write", ...], ... }
  }
}