> ## 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.

# AccountWorkspaceConnector

> AccountWorkspaceConnector is a per-entity junction record that tracks provenance for an Account → WorkspaceConnector association

AccountWorkspaceConnector is a per-entity junction record that tracks provenance for an Account → WorkspaceConnector association. Each row captures which connector (input or output) interacted with a given bank account, discriminated by direction, following the same `document_workspace_connectors` pattern. Tenant scope is inherited transitively through `account.workspace` and `workspaceConnector.workspace` — no direct `workspace_pk` column is stored on the junction itself. Rows are written exclusively by the connector sync pipeline and are never modified by users.

| Naming                          | Value                              |
| ------------------------------- | ---------------------------------- |
| Object                          | AccountWorkspaceConnector          |
| Resource type (JSON:API `type`) | `account_workspace_connector`      |
| Collection / records root       | — <sub>(not a records root)</sub>  |
| REST base                       | `/v1/account-workspace-connectors` |
| Entity class                    | `AccountWorkspaceConnector`        |

<Note>
  **Internal object.** Not currently exposed on the public REST API. The operations below describe the intended contract.
</Note>

## API operations

| Operation | Method & path                                  | Status     |
| --------- | ---------------------------------------------- | ---------- |
| List      | `GET /v1/account-workspace-connectors`         | 🟡 Planned |
| Retrieve  | `GET /v1/account-workspace-connectors/{id}`    | 🟡 Planned |
| Create    | `POST /v1/account-workspace-connectors`        | 🟡 Planned |
| Update    | `PATCH /v1/account-workspace-connectors/{id}`  | 🟡 Planned |
| Delete    | `DELETE /v1/account-workspace-connectors/{id}` | 🟡 Planned |

## Data model

### Attributes

| Field       | Type                               | Required | Constraints                                                                              | Allowed values                                                            | Description                                                                                                                              |
| ----------- | ---------------------------------- | -------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| direction   | 🔒 system — enum (direction\_enum) | ✅ Yes    | Native Postgres enum `core_api.direction_enum`; stored values are the enum VALUE strings | "input" (source / data collection), "output" (router / data distribution) | Indicates whether this workspace connector is acting as a data source (input) or a data sink/router (output) for the associated account. |
| created\_at | 🔒 system — datetime               | ✅ Yes    | Set on INSERT via `onCreate` hook; Postgres default `now()`. Never null.                 | —                                                                         | Timestamp when this provenance row was created by the connector sync pipeline.                                                           |
| updated\_at | 🔒 system — datetime               | ⚪ No     | Set on INSERT and again on every UPDATE via `onCreate` / `onUpdate` hooks. Nullable.     | —                                                                         | Timestamp of the last update to this row. Null until the first update occurs after creation.                                             |
| deleted\_at | 🔒 system — datetime               | ⚪ No     | Nullable; set to a timestamp on soft-delete, null when active.                           | —                                                                         | Soft-delete timestamp. When non-null the row is logically deleted. All queries must filter `deleted_at IS NULL`.                         |

### Relationships

| Name               | Type               | Required | Description                                                                                                                                                                                                                                               |
| ------------------ | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account            | to-one (ManyToOne) | ✅ Yes    | The bank account this provenance row is attached to. FK `account_pk` references `core_api.accounts.pk` ON UPDATE CASCADE. Tenant isolation for this junction is derived from the account's workspace.                                                     |
| workspaceConnector | to-one (ManyToOne) | ✅ Yes    | The workspace-scoped connector instance that interacted with the account. FK `workspace_connector_pk` references `core_api.workspace_connectors.pk` ON UPDATE CASCADE. Combined with `direction` this identifies the specific sync source or output sink. |

### System-computed

* pk — auto-increment serial primary key, internal only; never exposed on the public API.
* created\_at — set automatically via MikroORM `onCreate` hook (and Postgres default `now()`); not writable after insert.
* updated\_at — set automatically via MikroORM `onCreate` and `onUpdate` hooks; updated on every flush.
* deleted\_at — populated exclusively by soft-delete logic in the sync pipeline; no user-initiated deletion path.
* direction — written at row creation time by the connector sync orchestrator based on the connector's role; never changed after insert.
* No `workspace_pk` column: tenant scope is resolved by traversing the `account → workspace` or `workspaceConnector → workspace` relationship, consistent with the `document_workspace_connectors` design precedent.
* No UNIQUE constraint on (account\_pk, workspace\_connector\_pk, direction) — duplicate rows are allowed by design in the current schema; deduplication is deferred to iteration 3+ per migration comments.
* No `external_id` field — external object identity is deferred to a future iteration; this table records the connector pointer only.
* Rows are created exclusively by the connector sync pipeline (connector sync writer). There is no resource PATCH endpoint for this entity.

## Example

```json theme={null}
{
  "data": {
    "type": "account_workspace_connector",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "attributes": {
      "direction": "input",
      "created_at": "2026-05-10T08:14:22.000Z",
      "updated_at": "2026-05-10T08:14:22.000Z",
      "deleted_at": null
    },
    "relationships": {
      "account": {
        "data": { "type": "account", "id": "a1b2c3d4-0000-0000-0000-000000000001" }
      },
      "workspace_connector": {
        "data": { "type": "workspace_connector", "id": "d4c3b2a1-0000-0000-0000-000000000002" }
      }
    }
  }
}
```

<sub>Source: `apps/api/src/database/entities/AccountWorkspaceConnector.ts` · domain: ingestion · tier: Infrastructure</sub>