Workspace Connector

Documentation Index

Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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" }
    }
  }
}