Connections

Connections pull records from the tools your business already runs into your CCD workspace, so the agents can reason over the whole business. Every connection belongs to the workspace, has a named owner (the admin who connected it) and a recorded consent; only admins and owners can create or remove one.

There are two ways a tool connects. Both land records in the same knowledge graph, with the same provenance, and look the same to the agents.

Directly connected tools

Five providers connect straight from CCD with its own OAuth apps:

Provider	Scopes requested	What gets synced
Google Workspace	`contacts.readonly`, `calendar.readonly`	Contacts → contacts; calendar events → activities
HubSpot	`crm.objects.contacts.read`, `crm.objects.companies.read`, `crm.objects.deals.read`	Contacts, companies, deals
Salesforce	`api`, `refresh_token`, `offline_access`	Accounts → companies, contacts, opportunities → deals
QuickBooks	`com.intuit.quickbooks.accounting`	Customers → companies, invoices, expenses
Stripe (Connect)	`read_only`	Customers, invoices, payments

Synced records are written into your workspace's own tables (contacts, companies, deals, invoices, payments, expenses, activities) and from there into the knowledge graph. Each carries its provenance (metadata.hubspot_id, metadata.qb_id, …), which is how records show their source and how a later disconnect finds them. Contact email and phone written by a connector are field-encrypted with a blind index for lookups.

Scope discipline

Where a provider offers a read-only grant (Google, HubSpot, Stripe), that is all we request. QuickBooks and Salesforce have no read-only OAuth scope, so the grant is broad, but the connectors only read.

Two Google capabilities exist in code but are off by default because their scopes are not requested: Gmail sync (needs gmail.readonly, a restricted scope Google gates behind a security assessment) and calendar writes (needs calendar.events). The connector checks the granted scopes before calling either API.

Tools connected through the connector runtime

Everything else connects through Nango, an open-source connector runtime that runs inside the CCD deployment (on a self-hosted install, inside your stack). Available today: Xero (contacts, invoices) and monday.com (boards, items). Which providers an install offers is configured by its operator.

Nango runs the provider's OAuth and its sync scripts; CCD maps what it syncs into graph records of the right type — Xero contacts become companies, Xero invoices become invoices, monday boards become projects and items become tasks — with provenance pointing at the connection. These records are read-only mirrors: the tool you connected is the system of record, and CCD never writes back to it.

Connecting

Settings → Integrations → choose the tool → authorize → done. For directly connected tools the provider's consent screen opens in the same tab; for tools on the connector runtime a small window opens and closes when the tool is authorized. The connection shows Connected once the first sync starts.

Syncing

Scheduled: every connected tool is refreshed daily (02:30 UTC). Tools on the connector runtime also sync incrementally on the runtime's own schedule.
On demand: Settings → Integrations → Sync now.

If an access token has expired, it is refreshed with the stored refresh token. If the refresh fails (for example the grant was removed at the provider), the connection shows reconnect required instead of failing silently.

Where the tokens live

Directly connected tools: the access and refresh tokens are encrypted in CCD's database with AES-256-GCM under a per-workspace key, itself wrapped by ENCRYPTION_MASTER_KEY, which lives only in the environment.
Connector runtime: Nango holds the tokens, encrypted in its own database under its own key. CCD never stores them and never requests them — it reads only the records Nango has synced. On a self-hosted install the runtime, and therefore every token, runs on your infrastructure.

Each connection shows which of the two applies. See Security model.

Disconnecting

Settings → Integrations → Disconnect (admins only):

CCD revokes its grant: directly connected tools by token (Stripe by deauthorizing the connected account); runtime connections by deleting the connection in Nango, which discards the tokens. Revocation is best-effort.
Any stored credentials are deleted.
The connection is marked revoked and stops syncing.

Optionally tick also delete synced data to remove every record that connector created in the same step. Leave it unticked to keep those records, and the history and decisions built on them.

Personal connections

Connections to a person's own sources (an individual mailbox or calendar, visible to that member only) are modelled — one per member per provider, separate from the workspace connection — but there is no UI for them yet.

Self-host operator note

Directly connected tools need an OAuth app registered by the operator with the redirect URI https://<your-domain>/api/integrations/callback; client IDs and secrets go in .env (GOOGLE_CLIENT_ID, HUBSPOT_CLIENT_ID, SALESFORCE_CLIENT_ID, QUICKBOOKS_CLIENT_ID with matching *_CLIENT_SECRET; Stripe uses STRIPE_CLIENT_ID plus STRIPE_SECRET_KEY).

The connector runtime ships in the self-host bundle (nango-server). The operator creates each provider integration in its dashboard with their own OAuth app, deploys the sync scripts, and sets NANGO_SECRET_KEY and NANGO_PROVIDERS in .env. Full steps: integrations/nango/README.md in the repository.

Connectors need outbound network access to the provider. They do not work on an air-gapped install.