Manage extensions and connectors

Install, configure, version, and monitor extensions and connectors from the Backfill dashboard.

The SDK is for building extensions. This article is for everything that comes after: installing them in a workspace, wiring up connections, granting permissions, rolling versions forward and back, and watching them run.

Most of what’s below applies equally to extensions (defineExtension) and connectors (defineConnector). The differences are called out where they matter.

Where this lives in the dashboard

Open your workspace and head to Settings → Extensions. You’ll see two surfaces:

• Installed — the extensions and connectors active in this workspace, with their current version, recent activity, and a per-installation settings page.
• Catalog — anything available to install. First-party connectors (Stripe, Shopify, etc.) live here alongside any private extensions you’ve built and pushed to the workspace.

A workspace admin role is required for all install / uninstall / settings actions. Roles can be reviewed under Settings → Members.

Installing an extension

1. From the catalog, click into the extension and review its manifest summary: the permissions it requests (entities, HTTP hosts, secrets), the pages it adds, the UI contributions it makes, and the version about to install.
2. Click Install. For an extension with no required settings, that’s it — the new version is live.
3. For anything with required settings, the install drops you into a configuration form (see Configuring below) before activation.

You can install the same extension key into multiple workspaces independently. Each install carries its own settings, secrets, version, and logs.

Installing a connector

Connectors follow the same path with extra setup. After clicking Install:

1. Fill in connection settings. The dashboard renders a form from the connector’s connection.settingsSchema. Required fields are marked; secret fields render as password inputs and route into the encrypted secret store automatically.
2. Connect OAuth if required. OAuth connectors show a Connect action after required pre-OAuth settings are present. Backfill handles the provider redirect, callback, token storage, refresh, and reauth state.
3. Test the connection. Click Test connection. The dashboard hits the connector’s testConnection route with the credentials or host-managed OAuth connection. If it fails, the credentials don’t save until you fix them.
4. Wire up webhooks (if applicable). For connectors with a webhooks.endpoint, the dashboard generates a per-installation URL — copy it into the provider’s webhook configuration, paste their signing secret back into the form. Both halves are required for verified webhook delivery.
5. Activate. The connector starts polling its declared streams on schedule and accepts webhook deliveries immediately.

You can have multiple connections of the same connector running side by side — for example, a Stripe connector pointed at production and another pointed at a test account. Each connection is a separate row under Installed.

Configuring an extension or connector

Each install has a Settings page with three tabs:

• Settings — the user-configurable knobs your extension exposed via config (or via connection.settingsSchema for connectors). Edit and save; changes take effect immediately, no redeploy.
• Secrets — encrypted credentials. Set, rotate, or revoke. Values are write-only — the dashboard never displays an existing secret’s plaintext.
• Permissions — read-only summary of what the manifest requests. Permissions are baked into the manifest, so changing them requires a new version.

For connectors, the Connection tab adds: which streams are syncing, last successful poll per stream, webhook ingress health, and a re-test button.

Versions and rollback

Every deploy of an extension produces an immutable version. From the install’s Versions tab:

• Active — the version currently running.
• History — every version that has ever been deployed for this extension key, with timestamp and the developer who shipped it.
• Roll back — pick any prior version and make it active. The cutover is atomic; in-flight invocations finish on the previous version.

Two version states beyond plain “active”:

• Observation — a version deployed with backfill deploy --observe. Hooks fire, logs flow, but writes are intercepted. Use this to validate a candidate against live traffic; you’ll see all the work it would have done in the Logs tab. Promote it to live with Promote in the dashboard or backfill promote from the CLI.
• Draft — what backfill dev deploys behind the scenes. Auto-replaced on every save; not promoted to active. Drafts only fire for the developer’s session.

Permissions

The permissions an extension runs with are exactly what its manifest declares — no allow-by-default. The dashboard surfaces them at install time and on the Permissions tab post-install:

• Entities — which entity types the extension can read or write.
• HTTP — which https:// hosts it can reach.
• Secrets — which secret names it can read or write.

A workspace admin can review these any time but cannot widen them — to grant additional access, the developer ships a new version with an updated manifest. The dashboard will surface the diff at upgrade time.

Logs and monitoring

The Logs tab streams Log.debug / info / warn / error calls from every script in the extension. Filter by:

• Time range
• Log level
• Script type (hook / job / route / page action)
• Specific entity, event, route path, or job name

For connectors, the Connections tab shows per-stream sync status: last successful run, records ingested, current cursor, error counts, and webhook delivery rate. A stream stuck on its cursor or accumulating errors is the first signal something’s wrong upstream.

Errors thrown from before_save and other transactional hooks surface to the user who triggered the originating write — they see the validation message immediately. Errors from async paths (jobs, webhook handlers, sync routes) only surface in Logs; build alerting on top by querying the API at /v1/extensions/<key>/logs or wiring up your own webhook destination.

Disabling and uninstalling

Two ways to turn an extension off:

• Disable — the extension stays installed and configured, but stops firing hooks, jobs, and routes. Useful while debugging or when temporarily silencing a misbehaving connector. Re-enable to resume.
• Uninstall — removes the extension from the workspace entirely. Settings and secrets are deleted; custom entities the extension defined are not deleted (their data persists), but no new writes can target them until something is reinstalled with a matching defineEntity.

Disabling is reversible. Uninstalling drops the configuration; you’ll need to re-enter settings if you reinstall later.