Extensions

Extensions Overview

Extensions let you embed custom UI panels, receive live event webhooks, or do both — all from inside the Throttle dashboard and API surface, with an authenticated identity token, scoped API access, and signed event delivery.

Choose your extension shape

Backend integration

Subscribe to events and process them on your server. Use this for connectors, synchronization, and work that must continue when nobody has the dashboard open.

Embedded application

Render an iframe and use the bridge for verified identity and scoped API access. Use this for configuration, reports, and operator workflows.

Hybrid application

Combine a background event processor with an embedded management UI. Most full-service provider connectors eventually use this model.

Fulfillment connectors are backend-first
A ShipStation-style connector should synchronize orders, fulfillment, tracking, cancellations, and returns on its backend. An iframe can configure and monitor the connector, but synchronization cannot depend on the iframe being open.

What Throttle provides—and what you provide

Throttle

  • Catalog, version, installation, and marketplace workflows
  • Scoped credentials and signed iframe identity
  • Signed event delivery and installation configuration forms

Publisher

  • Hosting, persistence, queues, retries, and monitoring
  • Third-party credentials and provider-specific behavior
  • Support, privacy terms, incident response, and data lifecycle

External developers use public APIs, packages, the dashboard, and these docs. You do not need access to Throttle's private repository. Build your first private install.

Two-level model: catalog vs installs

Extensions live at two levels. The catalog is workspace-scoped: one extension definition per workspace, with a name, surfaces (iframe URL and/or webhook URL + events), and a list of requested scopes. An extension can be authored by your workspace and used only internally, or promoted to public for any Throttle workspace to install.

Installs are per-application. When a dashboard user installs an extension into an application, a single-use API key and (if a webhook URL is declared) a per-install signing secret are issued. Both are shown exactly once at install time. Multiple applications in the same workspace can each have their own independent installation of the same extension, with separate API keys, signing secrets, and configuration values.

Catalog browsing supports cursor pagination and search. Use q to search extension name, slug, author, and description, and installable=true to return only private/public extensions with a published version before pagination is applied.

Catalog (workspace-level)

  • POST /api/v1/extensions — create
  • GET /api/v1/extensions — list
  • PATCH /api/v1/extensions/:id — update manifest
  • POST /api/v1/extensions/:id/versions — create version
  • POST /api/v1/extensions/:id/versions/:vid/publish — publish
  • POST /api/v1/extensions/:id/lifecycle — promote/demote

Installs (application-level)

  • POST /api/v1/extensions/:id/install — install (pinned to a version)
  • GET /api/v1/installations — list for this app
  • POST /api/v1/installations/:id/upgrade — upgrade to new version
  • PATCH /api/v1/installations/:id/config — update config
  • POST /api/v1/extensions/:id/uninstall — uninstall

Surfaces

An extension manifest declares one or both surfaces. You can mix them freely.

UI iframe

Declare an iframeUrl in the manifest. The dashboard renders a sandboxed <iframe> at that URL when the extension panel is open. Your page calls createBridge() from @usethrottle/extension-bridge (or the hosted script tag) to handshake with the dashboard, obtain a signed identity token, and make authenticated API calls. See the Build guide and the Identity JWT reference .

Event webhooks

Declare a webhookUrl plus the list of eventSubscriptions your extension wants to receive. Throttle creates a managed webhook endpoint for the install and delivers signed events to that URL automatically. The per-install webhookSigningSecret is shown once at install time. See the Events reference .

Hybrid extensions
An extension can declare both iframeUrl and webhookUrl. The iframe bridge and the webhook delivery pipeline are independent — the bridge token gives the iframe REST access, while the webhook pipeline delivers async events to your server. Use both when you need a live UI panel and background event processing.

Lifecycle: draft → private → public

Every extension starts as draft. You iterate freely — create versions, update the manifest — before promoting it. 

stateDiagram-v2
  [*] --> draft: POST /extensions
  draft --> private: POST /extensions/:id/lifecycle (lifecycle=private)
  private --> draft: lifecycle=draft
  private --> public: lifecycle=public (admin only)
  public --> private: lifecycle=private
  draft --> [*]: DELETE /extensions/:id
Extension lifecycle transitions. Promoting to public requires the admin permission.
  • draft — visible only within your workspace; can only be installed by your own workspace's applications; no published version required.
  • private — still workspace-private but signifies the extension is production-ready. Installs within your workspace are in this state during internal testing.
  • public — listed in the global marketplace; any Throttle workspace can install it. Requires the application:extensions:admin permission. Throttle must enable the public marketplace for your workspace.

Versioning and pinned installs

Installs are always pinned to a specific published version. Publishing a new version does not automatically upgrade existing installs — each install retains the version it was pinned to until explicitly upgraded via POST /api/v1/installations/:id/upgrade. If the new version declares additional scopes, the installer must acknowledge them; Throttle returns 409 new_scopes_require_consent listing the delta. See the Versioning guide .

Environment isolation

Installs carry the workspace environmentId selected by the installing caller. A UAT install issues a UAT API key and receives only UAT events; a production install issues a production API key and receives only production events. The catalog itself (the extension definition and its versions) is shared across environments.