Extension Scopes

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.

// 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 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.

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.

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.