Skip to main content
A connector is a live OAuth integration with one provider — one Slack workspace, one Notion workspace, one Drive account, one Gmail mailbox. An organization can have multiple connectors of the same provider (e.g. two Slack workspaces) and they’ll be treated as distinct sources.

​
Lifecycle

pending → active → (error | disabled)
  • pending — OAuth callback completed, credentials encrypted and stored, first sync queued but not finished.
  • active — Sync running on schedule. The provider’s API is responsive.
  • error — Last sync failed. The connector card shows the error message; sync retries continue.
  • disabled — Manually disabled in the console. The scheduler skips it.

​
Sync schedule

The worker runs a scheduler tick every SYNC_POLL_INTERVAL_MS (default 5s). Any connector whose last_synced_at is older than AUTO_SYNC_INTERVAL_MIN (default 15 minutes) gets queued for a sync run. You can also trigger a manual sync via POST /v1/sync-runs or the Sync now button in the console. A full resync (fullResync: true) discards the cursor and re-ingests every source item — useful after a schema change or a connector reauthorization.

​
Credentials at rest

OAuth tokens are encrypted with AES-256-GCM using the ENCRYPTION_KEY_BASE64 master key. The encrypted bytes sit in the connectors.encrypted_credentials column. Plaintext tokens never touch the database, never leave the API process, never appear in logs. Rotating ENCRYPTION_KEY_BASE64 requires re-encrypting every connector row — there’s no built-in rotation tool yet. If you need this, contact support.

​
Provider-specific notes

Slack

Channels + threads + permalinks. Channel allowlist for noise control.

Notion

Pages + blocks. Per-page integration grant means narrow scope by default.

Google Drive

Docs, sheets, Markdown, CSV, PDF. Per-file ACLs preserved.

Gmail

Threads + headers + bodies. gmail.readonly scope.

​
Disconnecting

There’s currently no “Disconnect” button in the console UI. To remove a connector, contact support or (if self-hosted) delete the row from connectors and let the cascade clean up source items + embeddings.