Integrations

The integration.* family (17 verbs). Every verb enters through the one front door: it is capability-checked, permission-checked, scope-checked and audited before it runs (see Security & permissions). Each entry below lists its capability, risk class (which fixes the minimum autonomy level), the minimum caller permission, its availability tier, whether it is idempotent, and any outbound egress.

Createintegration.externalConnection.create

/Sensitive/Admin (DEFERRED). Persists a DB credential (password arrives ciphertext from the fe encryptPassword). Mints extconn_; created_by_id = acting user.

Call POST /v/integration.externalConnection.create with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.externalConnection.create.

Deleteintegration.externalConnection.delete

/Sensitive/Admin (DEFERRED). Fence id+workspace; relies on the DB FK ON DELETE CASCADE to clear external_sync_tables children. not-found -> BadInput.

Call POST /v/integration.externalConnection.delete with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.externalConnection.delete.

Updateintegration.externalConnection.update

/Sensitive/Admin (DEFERRED). Folds the config PATCH AND the post-test status write. { connectionId, name?, host?, port?, database?, username?, password?, ssl?, status?, lastTestedAt?, errorMessage? }. Fence id+workspace; not-found -> BadInput.

Call POST /v/integration.externalConnection.update with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.externalConnection.update.

Createintegration.hubspotLink.create

(DEFERRED, import-seat). Unique matter_id -> ON CONFLICT DO NOTHING + re-read. { matterId, templateId, hubspotTicketId, hubspotPipelineId, hubspotData, lastPulledAt }. Mints htl_.

Call POST /v/integration.hubspotLink.create with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.hubspotLink.create.

Updateintegration.hubspotLink.update

(DEFERRED, sync-seat). { linkId, hubspotData?, lastPulledAt?, lastPushedAt? }. Fence id+workspace.

Call POST /v/integration.hubspotLink.update with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.hubspotLink.update.

Createintegration.syncMapping.create

{ integrationId, objectType, informationTableId, fieldMappings, syncDirection?, enabled? }. Fence integration(type=hubspot) + table in workspace; unique (integration_id, object_type) -> Conflict. Mints sm_. NB informationTableId -> column clara_table_id.

Call POST /v/integration.syncMapping.create with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.syncMapping.create.

Deleteintegration.syncMapping.delete

{ mappingId }. Fence id+workspace; not-found -> BadInput.

Call POST /v/integration.syncMapping.delete with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.syncMapping.delete.

Updateintegration.syncMapping.update

(route config) OR service-seat (crm-sync run-status). Folds both. { mappingId, fieldMappings?, syncDirection?, informationTableId?, enabled?, lastSyncStatus?, lastSyncAt?, syncErrors?|null }. Fence id+workspace (the crm-sync sites previously lacked the fence).

Call POST /v/integration.syncMapping.update with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.syncMapping.update.

Updateintegration.syncTable.update

(DEFERRED, service-seat). { syncTableId, syncStatus?, syncError?|null, localTableId?, lastSyncedAt?, rowCount? }. Fence via JOIN external_connections.

Call POST /v/integration.syncTable.update with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.syncTable.update.

Upsertintegration.syncTable.upsert

(DEFERRED). Create-or-noop keyed (connection_id, external_schema, external_table). Fence via the parent connection in the workspace. Mints est_.

Call POST /v/integration.syncTable.upsert with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.syncTable.upsert.

Updateintegration.update

/Sensitive/Admin (DEFERRED, COURT-GATED credentials). { integrationId, enabled?, credentials?, config? }. Fence id+workspace; not-found -> BadInput.

Call POST /v/integration.update with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.update.

Createintegration.webhook.create

External/Sensitive (DEFERRED, COURT-GATED). The kernel MINTS the whsec_ secret (moved server-side) and returns it once. { url, events }. Mints id; binds workspace.

Call POST /v/integration.webhook.create with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.webhook.create.

Deleteintegration.webhook.delete

External (DEFERRED). { webhookId }. Fence id+workspace.

Call POST /v/integration.webhook.delete with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.webhook.delete.

Updateintegration.webhook.update

External (DEFERRED). { webhookId, url?, events?, isActive? }. Fence id+workspace; not-found -> BadInput.

Call POST /v/integration.webhook.update with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.webhook.update.

Deleteintegration.xeroLink.delete

{ matterId }. Fence workspace; not-found -> BadInput.

Call POST /v/integration.xeroLink.delete with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.xeroLink.delete.

Upsertintegration.xeroLink.upsert

1:1 keyed by matter_id. INSERT … ON CONFLICT (matter_id) DO UPDATE. Fence matter + connection in workspace. { matterId, connectionId, xeroObjectType, xeroObjectId, xeroData?, lastSyncedAt? }. xero_object_type is a plain string (the route validates the enum). Mints xol_.

Call POST /v/integration.xeroLink.upsert with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.xeroLink.upsert.

Upsertintegration.xeroReportCache.upsert

(DEFERRED, report-fetch seat). ON CONFLICT (connection_id, report_type, period_key) DO UPDATE. Fence connection in workspace. NO updated_at. Mints xrc_.

Call POST /v/integration.xeroReportCache.upsert with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool integration.xeroReportCache.upsert.