Extensions

Get Started with Extensions

Build and privately install a third-party app using only Throttle's public dashboard, APIs, packages, and documentation.

Before you begin

  • A Throttle workspace and application
  • Developer or Admin access to that application
  • Node.js 20 or newer for the recommended starter
  • A publicly reachable HTTPS URL during iframe or webhook development
  • The list of scopes an extension may request — extensions can only hold scopes marked extensionAllowed, which is a subset of the full API scope catalog. Naming any other scope in your manifest is rejected at publish time.
Partner status is not required to build
You can create, version, install, and test a private extension in your own workspace. Paid-plan or partner eligibility matters when you submit a public marketplace listing.

Your first private install

1

Choose an application in Test mode

Create or select a Throttle application and switch the dashboard to Test mode. Catalog entries belong to the publisher workspace; each installation belongs to one application and environment.

2

Prepare your application

Use the public starter repository when it is available, or host an HTTPS iframe, webhook handler, or both. Your extension never needs access to Throttle's private source repository.

3

Expose local endpoints over HTTPS

Use a secure development tunnel for your iframe and webhook endpoints. Keep the tunnel URL stable while configuring and testing the catalog entry.

4

Create a draft catalog entry

Open Extensions → Catalog, enter the iframe URL and/or webhook URL, select event subscriptions, and request only the scopes the app actually uses.

5

Publish a private version

Create version 0.1.0 from the draft manifest and publish it. Keep the extension private while developing and running acceptance tests.

6

Install it into the Test environment

Use the install wizard for the selected application. Capture one-time server credentials in a secret manager; never put them in browser code or source control.

7

Verify both surfaces

Confirm the iframe receives verified identity context and send a signed test event to the webhook. Inspect delivery logs and repeat a delivery to confirm idempotency.

You are done when

  • The iframe displays the verified workspace, application, environment, installation, and user context.
  • The webhook returns 2xx only after verifying the signature against the unmodified raw body.
  • Replaying the same event does not create duplicate provider work.
  • Uninstalling stops scheduled work and removes or disables the installation's provider connection.

Next, learn how to design the application, test failure cases, and prepare a marketplace submission.