Extensions

Build an Extension

This guide walks you from creating an extension catalog entry to having a working iframe panel with authenticated API access and live event delivery.

First time building an extension?
Start with the Get Started tutorial. This page explains architecture and API mechanics after your first private install.

Design for each installation

Treat every installation as an independent tenant connection. Store a server-side record keyed by installation ID with the workspace, application, environment, pinned extension version, provider account reference, encrypted credential reference, status, last successful sync cursor, timestamps, and uninstall state.

  • Throttle is the authority for whether an installation is active and which version and scopes it has.
  • Your backend is the authority for provider credentials, mapping state, cursors, retries, and reconciliation.
  • Never infer tenant identity from a provider account alone; validate the signed installation context.
  • Stop queued and scheduled work when an installation is suspended or uninstalled.

Choose where code runs

Browser iframe

Use for safe display settings and operator actions. Verify bridge identity and assume users can inspect all browser-delivered data.

Publisher backend

Use for provider secrets, event processing, scheduled synchronization, reconciliation, and privileged provider calls.

1

Create the extension in the dashboard

Go to Extensions in your workspace sidebar. Give it a name, declare your iframeUrl (for UI extensions) and/or a webhookUrl + eventSubscriptions (for event extensions), and list the scopes you need.

2

Create and publish a version

POST /api/v1/extensions/:id/versions to snapshot the current manifest as an immutable version, then POST /api/v1/extensions/:id/versions/:vid/publish to mark it installable.

3

Install into an application

POST /api/v1/extensions/:id/install with a versionId. The response includes a one-time API key and (if webhookUrl is declared) a webhookSigningSecret. The API key is shown once; the signing secret can be read back at any time.

4

Wire up the iframe bridge

In your iframe page, call createBridge() from @usethrottle/extension-bridge (npm) or load the hosted script. Wait for bridge.ready, then use bridge.api.* to call Throttle REST endpoints.

1. Create the extension

The extension manifest declares what surfaces your extension exposes, which scopes it needs, and which events it wants to receive. You can declare an iframeUrl, a webhookUrl with eventSubscriptions, or both. Every scope listed must be extensionAllowed — see the Scopes reference .

Create extension
# 1. Create the extension catalog entry
curl -X POST https://api.usethrottle.dev/api/v1/extensions \
  -H "Authorization: Bearer <dashboard-session>" \
  -H "content-type: application/json" \
  -d '{
    "name": "Inventory Sidebar",
    "iframeUrl": "https://extensions.example.com/inventory",
    "webhookUrl": "https://extensions.example.com/webhooks",
    "eventSubscriptions": ["order.created", "order.fulfilled"],
    "scopes": ["orders:read", "customers:read"]
  }'
# → { data: { id: "ext_...", name: "Inventory Sidebar", lifecycle: "draft", ... } }
Scopes are checked at register time
Every scope in the manifest is validated against the extensionAllowed flag when the extension is created or updated. Human and admin scopes (team_members:*, billing:*, admin:*, *) are never grantable to extensions and return 400 invalid_scope.

2. Create and publish a version

Versions are immutable snapshots of the manifest. Create a version when you're ready to make an installable release, then publish it. A version must be published before it can be referenced in an install call.

Version lifecycle
# 2. Create a version (snapshots the current manifest)
curl -X POST https://api.usethrottle.dev/api/v1/extensions/ext_xxx/versions \
  -H "Authorization: Bearer <dashboard-session>" \
  -H "content-type: application/json" \
  -d '{ "version": "1.0.0", "notes": "Initial release" }'
# → { data: { id: "ver_...", version: "1.0.0", status: "draft", ... } }
# 3. Publish the version (marks it installable)
curl -X POST https://api.usethrottle.dev/api/v1/extensions/ext_xxx/versions/ver_xxx/publish \
  -H "Authorization: Bearer <dashboard-session>" \
  -H "content-type: application/json" \
  -d '{}'
# → { data: { id: "ver_...", status: "published", ... } }

3. Install into an application

Installs are application-scoped and environment-scoped. The install response contains a one-time API key and, if a webhook URL is declared, the signing secret. Copy the API key immediately — it is shown exactly once. The signing secret is stable and readable at any time, so losing it is recoverable.

Install extension
# 4. Install into an application (requires X-Throttle-Application-Id header)
curl -X POST https://api.usethrottle.dev/api/v1/extensions/ext_xxx/install \
  -H "Authorization: Bearer <dashboard-session>" \
  -H "X-Throttle-Application-Id: <applicationId>" \
  -H "X-Throttle-Environment-Id: <workspace-environment-uuid>" \
  -H "content-type: application/json" \
  -d '{ "versionId": "ver_xxx" }'
# Response (store the API key immediately — shown once. The signing secret can be read back later.):
# {
#   "data": {
#     "id": "inst_...",
#     "extensionId": "ext_xxx",
#     "versionId": "ver_xxx",
#     "status": "active",
#     "environmentId": "8a5f2d1e-3d2a-4d24-93a1-fd3f9e1f37f0",
#     "environmentSlug": "uat",
#     "environmentKind": "non_production",
#     "providerEnvironment": "sandbox",
#     "apiKey": "sk_uat_...",             ← store this securely; shown once
#     "webhookSigningSecret": "whsec_..."  ← only present if webhookUrl was declared; readable later via GET /api/v1/installations/:id/webhook-secret
#   }
# }
Per-install secrets
The apiKey and webhookSigningSecret are unique to each install. Store them in your secrets manager. The API key is shown exactly once — losing it means uninstalling and reinstalling. The signing secret is stable and readable at GET /api/v1/installations/:id/webhook-secret. Copying either value into your extension by hand is deprecated and will be removed in a future release; use automatic setup.

4. Wire the iframe bridge

For UI (iframe) extensions, call createBridge() once at page load. The bridge sends a ready message to the dashboard, which responds with a signed session token and context. The token is automatically refreshed before it expires (10-minute TTL).

Option A — hosted script (no build step)

Hosted bridge
<!-- Option A: hosted script (no build step) -->
<script src="https://usethrottle.dev/docs/extension-bridge.v1.js"></script>
<script>
  const bridge = window.ThrottleBridge.createBridge({
    // Lock to the dashboard origin in production to prevent token leaks.
    targetOrigin: 'https://app.usethrottle.dev',
  });
  bridge.ready.then((ctx) => {
    console.log('Extension running as', ctx.user.email, 'in', ctx.environment.environmentSlug);
    // Call any Throttle API route the extension's scopes allow.
    bridge.api.get('/api/v1/orders?limit=10').then((res) => {
      console.log('Recent orders:', res.data);
    });
    // Resize the dashboard iframe panel to fit your content.
    bridge.resize(480);
    // Show a toast notification in the dashboard.
    bridge.toast('Inventory synced', 'success');
    // Ask the dashboard to navigate to another route.
    bridge.navigate('/orders');
  });
</script>

Option B — npm package

Install
npm install @usethrottle/extension-bridge
Bridge client
// Option B: npm package (React / bundled apps)
import { createBridge } from '@usethrottle/extension-bridge';
const bridge = createBridge({
  targetOrigin: 'https://app.usethrottle.dev',
});
// Await the session handshake
const ctx = await bridge.ready;
console.log('workspace:', ctx.workspace.slug, 'app:', ctx.application.slug);
console.log('environment:', ctx.environment.environmentSlug, 'role:', ctx.role);
console.log('scopes:', ctx.scopes);
// Authenticated REST calls using the pinned extension scopes
const orders = await bridge.api.get('/api/v1/orders?limit=5');
const customer = await bridge.api.get('/api/v1/customers/cust_xxx');
// Mutations (requires the relevant :write scope in the manifest)
await bridge.api.post('/api/v1/orders/ord_xxx/notes', { note: 'Inventory reserved' });
// UI helpers
bridge.resize(600);           // resize the iframe panel
bridge.toast('Done', 'info'); // show a dashboard toast
bridge.navigate('/orders');   // navigate the parent window
// Clean up when the component unmounts
bridge.destroy();
Bridge context
type SessionContext = {
  user: { id: string; email: string };
  workspace: { id: string; slug: string };
  application: { id: string; slug: string };
  environment: {
    environmentId: string;
    environmentSlug: string;
    environmentKind: 'production' | 'non_production';
    providerEnvironment: 'production' | 'sandbox';
  };
  installationId: string;
  extensionId: string;
  version: string;
  role: string;
  scopes: string[];
};
const ctx = await bridge.ready;
// Not included: configSchema, config values, API keys, or webhook signing secrets.
// Fetch config explicitly from an allowed API route or keep it server-side.

Sandbox flags and the full-width layout

The dashboard renders your iframe with allow-scripts allow-forms allow-same-origin allow-popups. A version can request more with sandboxFlags, chosen from allow-modals (native confirm() and alert()) and allow-downloads. Any other value is a validation error on the sandboxFlags field. The flags are part of the version: the merchant sees them in the install wizard next to the scopes, staff see them at review, and the iframe uses the flags of the version the installation is pinned to.

Sandbox flags
// Extra iframe sandbox flags, from a closed list of three. Optional.
// Register or update through POST / PATCH /api/v1/extensions, or in a manifest:
{
  "iframeUrl": "https://app.example.com/panel",
  "sandboxFlags": ["allow-modals", "allow-downloads"]
}

An editor-style extension can also ask for the whole viewport. The dashboard hides its side navigation and page padding for that iframe, and restores them when you send default, when the merchant navigates away, or when the iframe loads a new document with the bridge (a reload starts from the default layout, so ask again after bridge.ready). If your iframe navigates to a page that does not load the bridge, the full layout stays until the merchant navigates away or you ask for default first. The message needs @usethrottle/extension-bridge 1.2.0 or later.

Full-width layout
// Ask the dashboard for the full viewport below its top bar
// (no side navigation, no page padding).
const result = await bridge.setLayout('full'); // 'full' | 'default' | 'unsupported'
if (result === 'unsupported') {
  // An older dashboard never answered within 1 s: keep the compact layout,
  // for example by collapsing side panels below 1280 px.
}
// Give the normal dashboard layout back.
await bridge.setLayout('default');
Old dashboards
A dashboard without this feature ignores the message, so setLayout resolves 'unsupported' after one second. Both additions are optional: nothing changes for an extension that uses neither.

React pattern

React hook
// React hook pattern
import { useEffect, useRef, useState } from 'react';
import { createBridge, type Bridge, type SessionContext } from '@usethrottle/extension-bridge';
export function useExtensionBridge() {
  const bridgeRef = useRef<Bridge | null>(null);
  const [ctx, setCtx] = useState<SessionContext | null>(null);
  useEffect(() => {
    const bridge = createBridge({ targetOrigin: 'https://app.usethrottle.dev' });
    bridgeRef.current = bridge;
    bridge.ready.then(setCtx);
    return () => bridge.destroy();
  }, []);
  return { bridge: bridgeRef.current, ctx };
}
// In your extension component:
function InventorySidebar() {
  const { bridge, ctx } = useExtensionBridge();
  useEffect(() => {
    if (!bridge || !ctx) return;
    bridge.api.get('/api/v1/orders?limit=20').then((res: any) => {
      // render orders
    });
  }, [bridge, ctx]);
  return <div>...</div>;
}
Set targetOrigin in production
Always pass targetOrigin: 'https://app.usethrottle.dev' to createBridge(). Without it the bridge falls back to document.referrer or '*' as the postMessage target, which can leak the session token to other origins if the referrer is spoofed.
Config is explicit
The bridge does not pass configSchema or installed config values automatically. The dashboard consumes configSchema to collect settings during install and stores the resulting config on the installation record. See the configuration schema guide for the full lifecycle.

Deep links

A link to the launch page can open your iframe at a specific page. Add a page query parameter, and the dashboard loads your iframeUrl with that value as its URL fragment, so ?page=/products?x=1 opens <iframeUrl>#/products?x=1. Read location.hash in your iframe to route.

Build a deep link
// ctx is the session context the bridge hands you.
const link =
  `https://<dashboard>/w/${ctx.workspace.slug}/a/${ctx.application.slug}` +
  `/extensions/installs/${ctx.installationId}/launch` +
  `?page=${encodeURIComponent('/products?x=1')}`;

The value must be URL-encoded in the query string. The dashboard accepts it only when it is a string that starts with /, does not start with //, contains no \, no # and no control characters, and is at most 512 characters. Anything else is ignored and the iframe opens at its configured URL. An existing fragment on your iframeUrl is replaced. The page is applied when the iframe first loads; changing it later does not reload an open session.

Runtime model

A UI extension is loaded only after it is installed into an application. The dashboard opens the installed version's iframeUrl, creates a bridge host for that iframe origin, and mints a 10-minute extension-session JWT for the active dashboard user. Your iframe calls createBridge() once, sends a ready message to the parent, receives a session message, and then uses bridge.api for scoped REST calls.

The session token carries the installed version's scopes, application, workspace, environment, role, extension id, installation id, and version. It does not carry catalog authoring data such as configSchema, and it does not carry one-time install secrets. Event extensions use the separately generated webhook signing secret and verify incoming deliveries in their backend route.

Next steps

  • Identity JWT — the full claim set, TTL, JWKS verification, and using the token as an API bearer.
  • Events — verify the X-Throttle-Signature header and browse the full event catalog with required scopes.
  • Scopes — which scopes extensions may request and how scope ceilings work.
  • Versioning — immutable published versions, upgrades, and rollback.
  • Security model — RS256 JWKS, iframe sandboxing, origin pinning, scope ceilings.