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:
- Manifest declaration. You list the scopes your extension needs in
POST /api/v1/extensionsorPATCH /api/v1/extensions/:id.validateScopesForExtensionruns immediately — any scope withextensionAllowed: false(or an unknown scope) returns400 invalid_scope. - 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.
- Install.
POST /api/v1/extensions/:id/installpins the install to a version. The install's API key is granted exactly the version's scopes — no more, no less. - Iframe JWT. The launch-token endpoint mints a JWT whose
scopesclaim is the pinned version's scope list. Everybridge.api.*call is authorized against those 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
]
} // 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 neverextensionAllowedand cannot appear in an extension manifest. -
resource:writeimpliesresource:readon the same resource. For example,orders:writecoversorders:read. -
Read never implies write.
orders:readdoes NOT grantorders:write. -
No cross-resource implication.
orders:readdoes not grantcustomers:read. -
The buyer's email, name and phone in event payloads need
customer_pii:read. Without it they arrive asnull; 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.
# 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:readin your extension'sscopesand 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:readincluded; a key without it gets403 insufficient_scopes. - Parameters. Send exactly one of
qorids.qis 2–100 characters, matched as a case-insensitive prefix of the full name, the last name or the email, and answers up tolimitcustomers (1–20, default 10) ordered by email.idsis up to 50 comma-separated customer ids; every id found is answered, in the order given, and an integerlimitis ignored. Unknown ids are skipped. A search never lists an erased (anonymized) customer;idsstill names one, withname: null. Anything else is400 validation_error. - Answer. Only customers of the calling key's own workspace, application
and environment.
nameis the first and last name joined by a space, ornullwhen there is neither.nextCursoris alwaysnull: the directory answers one page. Responses carryCache-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?
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:readin your extension'sscopesand call with the installation's secret key. It is not sensitive and is never allowed on a publishable key; a key without it gets403 insufficient_scopes. - Parameter.
extensionIdis required and must be an extension id (a uuid). Anything else is400 validation_error. - Answer. Only for the calling key's own workspace, application and
environment.
installedis true only for anactiveinstallation (suspended and uninstalled answer false).versionis the pinned version label, ornullwhen not installed. Nothing else is exposed: no installation id, configuration, scopes or other extensions. Responses carryCache-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 forGET /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 forPOST /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 forPOST /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.
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— appadminanddeveloper. -
application:extensions:install— appadminanddeveloper. -
application:extensions:admin— required to promote an extension topublicor to delete a catalog entry. Onlyadminrole.
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
GET /api/v1/scopes.