Catalog connectors and connected accounts

Envoy exposes the connector types enabled in the deployed build. Some types are compiled into the binary; others are generated at boot from an approved connector catalog — one pickable type per catalog integration slug (for example zendesk, hubspot, salesforce). A Connector record supplies the environment-specific configuration for one type.

Tasks refer to connector slots, not Connector record IDs or credentials. See Connectors overview for the compiled types.

How catalog types are registered

At startup, registerCatalogConnectors (src/connectors/catalog-connector.ts) reads the deployment's catalog settings, lists every catalog entry, and calls createCatalogConnectorClass to register one connector type per integration slug. The type string is the lowercased slug. If a slug collides with a compiled connector type, the compiled type wins and the catalog entry is skipped.

The catalog itself comes from one of two providers:

• a catalog service, configured with clove_url and clove_token;
• a local integrations directory, configured with integrations_dir (plus optional docs_dir and owner).

On the control plane these settings live under the cardamom: key of the server configuration file — see Server configuration. Task subprocesses, HTTP executors, and the CLI register the same types from environment variables (ENVOY_CATALOG_INTEGRATIONS_DIR or ENVOY_CLOVE_URL/ENVOY_CLOVE_TOKEN) via ensureCatalogConnectorsFromEnv, so a task that names a catalog type resolves it in every execution path.

A catalog connector's editable configuration is intentionally small: a single integrated_account_id field that pins the connected account. Provider URLs and tokens come from deployment defaults, not from each Connector record.

Availability varies by deployment

The connector picker reports every available type and its configuration schema. If a task bundle requires a type that is not available, ask the deployment administrator to include it; renaming the connector type does not make the task compatible.

Create a connector

1. Open Connectors and choose New connector.
2. Select the type.
3. Enter a name that describes the account and environment.
4. Complete the generated configuration form.
5. Store secret values through the supported secret input.
6. Save and run the available connection or discovery test.

Use separate Connector records for production and test accounts. A task can bind to either record without changing its YAML. The full operator flow, including the connect and OAuth-app screens, is covered in Connectors and connected accounts.

Connected accounts

Catalog connectors separate the integration (which SaaS product) from the connected account (which tenant or login within it). Connecting works like this at a reference level:

1. Connect account on the Connector opens a hosted connect flow that runs the OAuth authorization or API-key form for the integration.
2. When the flow completes, the browser returns to Envoy and the new account is validated and pinned onto the Connector as integrated_account_id.
3. At call time, credentials for that account are resolved from the credential broker; Envoy does not store third-party OAuth tokens itself. Expired tokens are refreshed transparently.

Method calls may pass integrated_account_id explicitly to target a different account; when omitted, the pinned account is used. The account ID is not a credential, but it is environment-specific — use template arguments when it should be fixed at job creation.

Some integrations require a customer-supplied OAuth app (bring your own app). For those, setup lives on the Connectors → OAuth apps screen — the connector dialog shows the setup status and links to it — and Connect account stays disabled until the OAuth app credentials are saved.

File-backed connectors

Supported connectors can upload files through the connector editor. Use the returned managed path or resource identifier in task configuration.

In container deployments, paths must be visible inside the control-plane and executor containers. Do not rely on a workstation path that is not mounted into the deployment.

Uploaded files can contain customer data. Apply the same retention, access, and backup controls as other source data.

Introspection and option discovery

Connector-backed pickers and Data Explorer use introspection methods to list resources, fields, accounts, or options. Large lists must be searched and paged on the server.

Discovery is not a write path. Do not configure option sources with methods that mutate the external system.

Promotion between environments

Task and job-template bundles contain connector slot names and types, not Connector records or secrets. On the target:

1. verify required connector types are available;
2. create target Connector records;
3. test network access and permissions;
4. create or upgrade the job;
5. bind template connector names to target records;
6. run a bounded validation.

Never export credentials as part of a documentation or bundle workflow.

Related

• Connectors overview — the compiled connector types
• Connectors and connected accounts — the operator flow in the UI
• Server configuration — where catalog settings live
• Truto — a compiled connector with a similar integrated-account model