Extensions

Extension Scopes

Extensions operate within a strict scope ceiling. Only scopes marked extensionAllowed may appear in an extension manifest. Human, admin, and management scopes are never grantable to extensions.

Choose the smallest scope set that supports demonstrated behavior. Once selected, continue to installation and configuration.

How scopes flow

Scopes are declared in the extension manifest, snapshotted into a published version, and issued to an install. At each stage Throttle enforces the extensionAllowed ceiling:

  1. Manifest declaration. You list the scopes your extension needs in POST /api/v1/extensions or PATCH /api/v1/extensions/:id. validateScopesForExtension runs immediately — any scope with extensionAllowed: false (or an unknown scope) returns 400 invalid_scope.
  2. Version snapshot. When you publish a version, the manifest scopes are frozen into the version record. Subsequent manifest edits do not change the published version.
  3. Install. POST /api/v1/extensions/:id/install pins the install to a version. The install's API key is granted exactly the version's scopes — no more, no less.
  4. Iframe JWT. The launch-token endpoint mints a JWT whose scopes claim is the pinned version's scope list. Every bridge.api.* call is authorized against those scopes.
Manifest with scopes
// Extension manifest with scopes
{
  "name": "Order Inspector",
  "iframeUrl": "https://extensions.example.com/orders",
  "webhookUrl": "https://extensions.example.com/webhooks",
  "eventSubscriptions": ["order.created", "order.updated", "payment.captured"],
  "scopes": [
    "orders:read",     // required for order.* events + GET /api/v1/orders
    "payments:read",   // required for payment.* events + GET /api/v1/payments
    "customers:read"   // optional — allows reading customer records
  ]
}
Scope ceiling in practice
// The extension's JWT token carries the scopes from the pinned version.
// Calling a route that requires a scope not in that list returns:
// HTTP 403 { error: { code: "insufficient_scopes", ... } }
// Good — orders:read is in the manifest scopes:
const orders = await bridge.api.get('/api/v1/orders?limit=10');
// Bad — payment_refunds:write is NOT extensionAllowed; the manifest
// would have been rejected at registration time:
// await bridge.api.post('/api/v1/payments/pay_xxx/refund', { amount: 500 });
// → 400 invalid_scope at extension create/update time

Scope implication rules

The same implication rules that apply to API keys apply to extension scopes:

  • * covers all scopes — but * is never extensionAllowed and cannot appear in an extension manifest.
  • resource:write implies resource:read on the same resource. For example, orders:write covers orders:read.
  • Read never implies write. orders:read does NOT grant orders:write.
  • No cross-resource implication. orders:read does not grant customers:read.
  • The buyer's email, name and phone in event payloads need customer_pii:read. Without it they arrive as null; addresses are still delivered. See customer contact fields .

Finding customers: customer_directory:read

An extension that shows or picks customers (for example a customer-group member list) needs their names, not their records. customer_directory:read answers only id, name and email, without customers:read and the PII, addresses and stored cards it carries.

GET /api/v1/customer-directory
# Search: a case-insensitive prefix of the name, the last name or the email
curl "https://api.usethrottle.dev/api/v1/customer-directory?q=jan&limit=5" \
  -H "X-API-Key: $INSTALLATION_API_KEY"

# Name a page of known customers: up to 50 ids, comma-separated
curl "https://api.usethrottle.dev/api/v1/customer-directory?ids=<id1>,<id2>" \
  -H "X-API-Key: $INSTALLATION_API_KEY"

# 200, Cache-Control: no-store
# { "data": [ { "id": "c3d4e5f6-0a1b-4c2d-8e3f-4a5b6c7d8e9f",
#               "name": "Jane Doe",
#               "email": "jane@example.com" } ],
#   "nextCursor": null }
  • Scope. List customer_directory:read in your extension's scopes and call with the installation's secret key. The merchant sees it at install as "Find customers by name or email", among the other requested scopes. It is sensitive, so no OAuth connection can hold it. No other scope grants it except full access (*), customers:read included; a key without it gets 403 insufficient_scopes.
  • Parameters. Send exactly one of q or ids. q is 2–100 characters, matched as a case-insensitive prefix of the full name, the last name or the email, and answers up to limit customers (1–20, default 10) ordered by email. ids is up to 50 comma-separated customer ids; every id found is answered, in the order given, and an integer limit is ignored. Unknown ids are skipped. A search never lists an erased (anonymized) customer; ids still names one, with name: null. Anything else is 400 validation_error.
  • Answer. Only customers of the calling key's own workspace, application and environment. name is the first and last name joined by a space, or null when there is neither. nextCursor is always null: the directory answers one page. Responses carry Cache-Control: no-store; do not store the answer either.
  • Rate limit. Its own budget, 300 calls a minute per API key (per installation for calls from your iframe session) and environment. Over it you get 429 rate_limit_exceeded.

Checking another extension: extension_presence:read

An extension that adds features when a companion extension is present (for example a page builder that shows catalog widgets only when the Product Catalog is installed) asks one narrow question: is extension X installed here?

GET /api/v1/extension-presence
curl "https://api.usethrottle.dev/api/v1/extension-presence?extensionId=<extension-uuid>" \
  -H "X-API-Key: $INSTALLATION_API_KEY"

# 200, Cache-Control: no-store
# { "data": { "installed": true, "version": "1.4.0" } }
# Not installed here: { "data": { "installed": false, "version": null } }
  • Scope. List extension_presence:read in your extension's scopes and call with the installation's secret key. It is not sensitive and is never allowed on a publishable key; a key without it gets 403 insufficient_scopes.
  • Parameter. extensionId is required and must be an extension id (a uuid). Anything else is 400 validation_error.
  • Answer. Only for the calling key's own workspace, application and environment. installed is true only for an active installation (suspended and uninstalled answer false). version is the pinned version label, or null when not installed. Nothing else is exposed: no installation id, configuration, scopes or other extensions. Responses carry Cache-Control: no-store; cache the answer yourself for a few minutes if you ask often.

Management scopes for extensions

The management scopes (extensions:read, extensions:write, extensions:install) control who can author and install extensions. These are Taxonomy B (human) scopes — they are not extensionAllowed. Extensions cannot manage other extensions.

Management scope summary

  • extensions:read — view the extension catalog and installation list. Required for GET /api/v1/extensions, GET /api/v1/extensions/:id, GET /api/v1/extensions/:id/versions, GET /api/v1/installations, GET /api/v1/installations/:id/deliveries.
  • extensions:write — author, version, and publish extensions. Required for POST /api/v1/extensions, PATCH /api/v1/extensions/:id, POST /api/v1/extensions/:id/versions, POST /api/v1/extensions/:id/versions/:vid/publish , POST /api/v1/extensions/:id/lifecycle (draft/private).
  • extensions:install — install, configure, and manage installs. Required for POST /api/v1/extensions/:id/install, POST /api/v1/extensions/:id/uninstall, PATCH /api/v1/installations/:id/config, POST /api/v1/installations/:id/upgrade, POST /api/v1/installations/:id/launch-token, POST /api/v1/installations/:id/deliveries/:deliveryId/replay , POST /api/v1/installations/:id/test.
install does not imply write or read
The extensions:install scope is a custom action — it is independent of extensions:write and extensions:read. Granting only extensions:install to a key lets it manage installations without being able to author or list the catalog.

Team RBAC for extension management

Dashboard (Clerk) callers are additionally gated by RBAC permissions, not just scopes. The relevant RBAC keys are:

  • application:extensions:read — all app roles ( admin | developer | finance | viewer).
  • application:extensions:write — app admin and developer.
  • application:extensions:install — app admin and developer.
  • application:extensions:admin — required to promote an extension to public or to delete a catalog entry. Only admin role.

Workspace owners and workspace admins have implicit admin role on every application. See the Permissions reference for the full role-capability matrix.

Extension-allowed scope catalog

The following scopes may appear in an extension manifest. They are all extensionAllowed: true and sourced directly from the live scope registry — they update automatically when new scopes are added.

Applications

  • applications:read — View applications
  • applications:write — Manage applications

Carts

  • carts:read — View carts
  • carts:write — Manage carts
  • cart_items:write — Manage line items
  • checkout_sessions:read — View checkout sessions
  • checkout_sessions:write — Manage checkout sessions

Connected apps

  • oauth_grants:read — View Builder OAuth connections
  • oauth_grants:write — Revoke Builder OAuth connections

Connectors

  • connectors:read — View connectors
  • connectors:write — Manage connectors

Customers

  • customers:read — View customers
  • customers:write — Manage customers
  • customer_pii:read — View customer PII (sensitive)
  • customer_addresses:read — View addresses
  • customer_addresses:write — Manage addresses
  • customer_payment_methods:read — View stored cards (sensitive)
  • customer_payment_methods:write — Manage stored cards (sensitive)
  • customer_tokens:read — Check shoppers' sign-in tokens
  • customer_directory:read — Find customers by name or email (sensitive)
  • customer_groups:read — View customer groups

Discounts

  • discounts:read — View discounts
  • discounts:write — Manage discounts

Extensions

  • extension_presence:read — Check whether an extension is installed

Forms

  • forms:read — View site forms and their submissions (sensitive)
  • forms:write — Manage site forms (sensitive)

Fulfillments

  • fulfillments:read — View fulfillments
  • fulfillments:write — Manage fulfillments
  • fulfillment_shipments:write — Update shipments
  • fulfillment_digital:read — View digital delivery
  • fulfillment_digital:write — Manage digital delivery
  • fulfillment_access:write — Manage access credentials
  • fulfillment_services:write — Manage service fulfillment

Invoices / AR

  • invoices:read — View invoices & aging
  • invoice_payments:write — Mark invoices paid (sensitive)
  • invoice_dunning:write — Send dunning notices

Media

  • media:read — View the media library
  • media:write — Upload and manage media library images

Orders

  • orders:read — View orders
  • orders:write — Manage orders
  • order_cancellations:write — Cancel orders
  • order_returns:read — View returns
  • order_returns:write — Process returns
  • order_comps:write — Comp orders (write off the balance) (sensitive)
  • order_holds:write — Freeze and unfreeze orders

Payments

  • payments:read — View payments
  • payments:write — Create payments
  • payment_authorizations:write — Authorize payments
  • payment_captures:write — Capture payments
  • payment_refunds:read — View refunds (sensitive)
  • payment_refunds:write — Refund payments (sensitive)
  • payment_voids:write — Void payments (sensitive)
  • payment_records:write — Record payments received outside Throttle (sensitive)
  • payment_disputes:read — View disputes (sensitive)
  • payment_disputes:write — Handle disputes (sensitive)
  • payment_methods:read — View payment methods (sensitive)
  • payment_methods:write — Tokenize payment methods (sensitive)

Quotes

  • quotes:read — View quotes
  • quotes:write — Manage quotes

Scripts

  • storefront_scripts:read — Load storefront scripts
  • storefront_scripts:write — Report storefront script load outcomes

Shipping & Tax

  • shipping_tax:read — View shipping/tax config
  • shipping_tax:write — Edit shipping/tax config
  • shipping_tax_publications:write — Publish shipping/tax config
  • shipping_quotes:write — Request shipping quotes
  • tax_calculations:write — Calculate tax
  • shipping_tax_quote_tokens:read — View quote tokens
  • shipping_tax_quote_tokens:write — Manage quote tokens
  • shipping_tax_snapshots:write — Accept external snapshots

Subscriptions

  • subscriptions:read — View subscriptions
  • subscriptions:write — Manage subscriptions
  • subscription_pauses:write — Pause/resume subscriptions
  • subscription_cancellations:write — Cancel subscriptions

Webhooks & Events

  • webhooks:read — View webhooks
  • webhooks:write — Manage webhooks
  • webhook_deliveries:read — View deliveries
  • webhook_deliveries:write — Retry deliveries
  • events:read — View events
  • audit_logs:read — View audit log
  • activity:write — Add history entries to records

Workspace

  • merchant:read — View workspace settings
  • merchant:write — Edit workspace settings
  • embed_config:read — View embed config
  • embed_config:write — Edit embed config
  • branding:write — Upload branding assets
Full scope catalog
The complete scope catalog, including non-extension scopes, is at API key scopes and served live at GET /api/v1/scopes.