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 stateless compute scopes only — shipping_quotes:write and tax_calculations:write — and can never read carts, orders, customers, payment methods, or PII. (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

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", ...], ... }
  }
}