Connector

A Connector is a catalog entry that describes one integration point Well supports — a source of data to pull in (direction=input) or a destination to push data out to (direction=output). The catalog is seeded centrally and workspace-agnostic: it defines the provider, auth flow, transport, and which Well entity models a sync can populate, but carries no per-workspace credentials or state. Workspace-level activation and OAuth tokens live on the WorkspaceConnector join entity. A Connector is referenced by WorkspaceConnector (per-workspace activation), ConnectorFilter (routing rules), and ProviderConnector (blueprint-provider pairings).

API operations

Data model

Attributes

Relationships

System-computed

• connector_id is generated by PostgreSQL gen_random_uuid() at INSERT time via MikroORM defaultRaw. It is unique and immutable after creation.
• created_at is set to new Date() on INSERT via the MikroORM @Property({ onCreate }) lifecycle hook. Never updated after creation.
• updated_at is set to new Date() on both INSERT and UPDATE via MikroORM @Property({ onCreate, onUpdate }) hooks. Reflects the last catalog modification.
• deleted_at is null by default (no MikroORM onDelete lifecycle — soft-delete is performed by setting the field explicitly in the service layer). All list queries must apply a WHERE deleted_at IS NULL predicate. The partial index idx_connectors_status_created_at only covers rows WHERE deleted_at IS NULL.
• The Connector catalog is seeded centrally via apps/api/src/database/seed.ts (143 entries as of Q2 2026, 92 of which use transport=mcp). Connector rows are workspace-agnostic — they carry no per-workspace state. Per-workspace auth tokens and sync configuration live exclusively on WorkspaceConnector.config.
• status defaults to unavailable at the database level (StatusTypeEnum.UNAVAILABLE). The seed overrides most live integrations to available; connectors under development ship as coming_soon.
• direction defaults to input at the database level (DirectionEnum.INPUT).
• authorization_flow defaults to none at the database level (AuthorizationFlowEnum.NONE).
• transport defaults to api at the database level (TransportEnum.API).
• auth_config.mcp_server_url is the MCP entry point URL for transport=mcp connectors. Per-workspace client_id, client_secret, access_token, refresh_token, and dcr_access_token are stored in WorkspaceConnector.config, never in auth_config.
• slug, when set, is the key into apps/api/src/mcps/<slug>/ for per-provider GENERATED shim files (config.ts, tools.json, connector-seed.ts). These generated files must not be hand-edited — the source of truth is packages/mcp-generator/configs/<slug>.yaml.
• supported_target_models drives the sync orchestrator's target model selection. Valid values from the 12-model catalog: company, people, invoice, transaction, account, ledger_account, journal, journal_entry, email, payment_means, invoice_transaction, document.
• Three compound indexes exist on the connectors table: idx_connectors_status on (status); idx_connectors_direction_status on (direction, status); idx_connectors_status_created_at partial index on (status, created_at DESC) WHERE deleted_at IS NULL — optimised for the hot-path connector marketplace list query.

Example

{
  "data": {
    "type": "connector",
    "id": "a1b2c3d4-e5f6-4a8b-9c0d-454545000001",
    "attributes": {
      "connector_id": "a1b2c3d4-e5f6-4a8b-9c0d-454545000001",
      "name": "Stripe",
      "provider": "well",
      "category_id": "finance",
      "service_id": "stripe",
      "external_connector_id": null,
      "slug": "stripe",
      "status": "available",
      "direction": "input",
      "authorization_flow": "oauth-dcr",
      "transport": "mcp",
      "auth_config": {
        "oauth_metadata_url": "https://mcp.stripe.com/.well-known/oauth-authorization-server",
        "mcp_server_url": "https://mcp.stripe.com"
      },
      "supported_target_models": [
        "company",
        "people",
        "invoice",
        "transaction",
        "account",
        "ledger_account",
        "payment_means",
        "invoice_transaction"
      ],
      "created_at": "2025-09-01T08:00:00.000Z",
      "updated_at": "2026-03-15T10:22:00.000Z",
      "deleted_at": null
    }
  }
}