Workspace Connector

A workspace_connector is an activation record that binds a generic Connector definition to a specific workspace, creating a live, credentialed integration instance. It is the unit of auth lifecycle management: it carries the per-workspace OAuth credentials (access token, refresh token, DCR client ID) inside an optional JSONB config column, tracks the lifecycle status of the integration, and optionally links to the Person who owns or administers the connection. Every sync run, connector mapping, and sync diagnostic in the pipeline is scoped to a workspace_connector. It serves as the FK target for junction tables ({entity}_workspace_connectors, workspace_connector_sync_targets, workspace_connector_sync_logs) and is the sourceWorkspaceConnector provenance pointer on ingested entities.

API operations

Data model

Attributes

Relationships

System-computed

• workspace_connector_id is generated via randomUUID() on the MikroORM onCreate hook — equivalent to gen_random_uuid() in Postgres.
• created_at is set once on onCreate and is immutable. updated_at is refreshed on every onUpdate lifecycle call.
• deleted_at follows the platform-wide soft-delete convention: null = active, non-null = soft-deleted. Downstream queries and Hasura RLS always filter deleted_at IS NULL.
• config is a free-form JSONB column typed as Record<string, any> in the ORM. At runtime it is cast to McpOAuthWorkspaceConfig by McpOAuthService. The known sub-fields are: client_id, client_secret, dcr_access_token, access_token, refresh_token, token_expires_at, pkce_code_verifier (ephemeral — cleared after PKCE exchange), pkce_state (ephemeral — cleared after callback), plus provider-specific keys written back after token exchange (e.g. tenant info).
• filter is a virtual (non-persisted) property. WorkspaceConnectorRepository resolves it at query time by finding either a workspace-scoped ConnectorFilter or the connector template filter. It does not correspond to any column on the workspace_connectors table.
• The internal pk is an auto-increment integer used exclusively for FK joins. All public-facing references use workspace_connector_id (UUID).
• OAuth state tracking for PKCE flows: McpOAuthService.getAuthorizationUrl() writes pkce_code_verifier and pkce_state into config before redirect; McpOAuthService.exchangeCodeForTokens() clears them and writes access_token, refresh_token, token_expires_at in their place.
• DCR (Dynamic Client Registration): McpOAuthService.ensureClientRegistered() checks config.client_id before writing a new DCR client. Each workspace_connector gets its own OAuth client registered with the provider — DCR is per-workspace-connector, not per-connector-template.
• Token refresh buffer: McpOAuthService refreshes when token_expires_at is within 5 minutes of expiry (enforced as an architectural constant).
• The junction tables {entity}_workspace_connectors (company, people, account, invoice, transaction, document) reference workspace_connector_pk via FK — they track which connector ingested each entity row, with direction discrimination (input vs output).
• workspace_connector_sync_targets was backfilled via Migration20260527140000 with a 1:1 self-pointing row for every active pre-existing connector to preserve legacy single-workspace ingestion semantics.
• Composite idx_workspace_connectors_workspace_deleted on (workspace_pk, deleted_at) supports the hot-path workspace-scoped connector list query. Additional indexes on connector_pk, person_pk, and status support secondary traversals.
• The WorkspaceConnectorSyncLog relationship carries deleteRule: 'cascade' on the child side — hard-deleting a workspace_connector row cascades to remove all associated sync log rows.

Example

{
  "type": "workspace_connector",
  "id": "a3c7e2b1-84f0-4d1e-9c3a-0f2b6d8e1a7c",
  "attributes": {
    "workspace_connector_id": "a3c7e2b1-84f0-4d1e-9c3a-0f2b6d8e1a7c",
    "status": "enabled",
    "config": {
      "client_id": "well_dcr_abc123",
      "dcr_access_token": "ey...",
      "access_token": "ey...",
      "refresh_token": "rt_xyz789",
      "token_expires_at": "2026-06-02T18:00:00.000Z"
    },
    "created_at": "2026-02-14T10:23:00.000Z",
    "updated_at": "2026-06-01T08:42:11.000Z",
    "deleted_at": null
  },
  "relationships": {
    "connector": {
      "data": { "type": "connector", "id": "b8f1d3a2-5c20-4e6b-8d4a-1e9c7f3b2d01" }
    },
    "workspace": {
      "data": { "type": "workspace", "id": "9f3e1c7a-2d44-4b8e-a1f5-0c6b3e9d7e42" }
    },
    "person": {
      "data": { "type": "people", "id": "d4a2c8f0-1b35-4c7d-90e2-5f8a6b3c1d20" }
    }
  }
}