Connectors Overview

A connector lets the platform access an external source such as Gmail, Google Drive, Google Calendar, Google Contacts, Microsoft Calendar, Microsoft Contacts, OneDrive, Outlook, SharePoint, OneNote, Slack, Jira, GitHub, or Odoo. OAuth connectors bind one explicit linked account plus any provider-specific configuration or scoped resource selection required to scope that connector. User-managed API-key/PAT connectors encrypt one signed-in user’s provider credential in API-owned storage. Deployment API-key connectors bind deployment-owned credentials configured by the customer CMS operator and do not use Better Auth linked accounts. Today, one external linked OAuth account still belongs to one app user only; sharing the same provider account across different app users would require a higher-level app sharing model above Better Auth linked accounts. This page gives the product-level connector shape and current provider status without repeating the full connectors spec.

Connectors In This Repo Today

Google Drive: live file document search is the default, indexed mode is optional, and provider-backed connector-resource-list browsing is implemented for picker/focus flows.
Google Calendar: live-only calendar event list/search/recent access is implemented through Google Calendar API calendar discovery and event lookup; no calendar sync or embeddings are implemented.
Google Contacts: live-only saved-contact search and list access is implemented through Google People API people.searchContacts and people.connections.list; Google Workspace Directory people are not part of the connector scope.
OneDrive: live file document search is the default, indexed mode is optional, and provider-backed connector-resource-list browsing is implemented for picker/focus flows.
Microsoft Calendar: live-only calendar event list/search access is implemented through Microsoft Graph calendar discovery, calendarView, and Search event results; this is separate from the Outlook mail connector.
Microsoft Contacts: live-only Microsoft 365 people/contact lookup is implemented through Microsoft Graph Search person results plus /me/contacts saved-contact listing; this is separate from the Outlook mail connector.
SharePoint: live-only Microsoft Graph access is implemented for selected SharePoint sites, site pages, document-library files/folders, lists, list items, columns, and bounded file/page reads. It uses the shared knowledge-page, file-resource, and business-record domains and requires selected sites.
OneNote: live-only Microsoft Graph access is implemented for selected notebooks, section groups, sections, pages, hierarchy, and bounded page HTML/text reads. It uses the shared knowledge-page domain and requires selected notebooks.
Gmail: live mail search is implemented; indexed mode is also supported.
Outlook: live mail search is implemented; indexed mode is also supported.
Slack: live-only workspace-chat access is implemented through assistant.search.context, with one bounded conversations.replies or conversations.history follow-up available for the top grounded message when extra context is needed.
Jira: live-only work-item access is implemented with OAuth, Jira Data Center user-managed PATs, and Jira Data Center company-managed service/bot PATs. OAuth uses one selected Atlassian site per connector, while Data Center PAT paths use the configured base URL and project-scoped access.
Confluence: live-only knowledge-page access is implemented with Cloud OAuth, Confluence Data Center user-managed PATs, and Confluence Data Center company-managed service/bot PATs. It supports bounded spaces/pages/comments/labels/tree/attachment-metadata reads with required spaces selection and no indexed page-content storage.
Odoo: live-only business-record access is implemented through Odoo JSON-2 with either the signed-in user’s own API key or a company-managed deployment API-key profile configured in the customer CMS. Odoo does not use Better Auth OAuth, Meltano sync, embeddings, or write methods.

Connector Auth Strategies

The connector implementation keeps auth strategy handling connector-agnostic:

oauth: the user connects their own provider account through Better Auth connector OAuth. The provider sees the user’s provider account, and duplicate prevention uses the linked account plus any required config scope.
user-api-key: the user enters their own API key or PAT in the web app. API validates it with the provider, encrypts it with API-owned user credential storage, and scopes it to that user and connector row.
deployment-api-key: a customer CMS operator configures a company-managed API key or service/bot PAT. The provider sees that service/bot identity, not the signed-in web user, and existing company-managed rows fail closed if the CMS profile is removed or invalid.

See Provider Auth And Setup for the shared storage and validation model, Jira for OAuth plus Data Center PAT behavior, Confluence for Cloud OAuth plus Data Center PAT behavior, and Odoo for JSON-2 API-key setup.

Live Vs Indexed

live means the system queries the provider directly at runtime.
indexed means provider data is synced, normalized, chunked, embedded, and stored for retrieval inside the platform.
Indexed mode stores extracted chunk text with vectors so Mastra/Qdrant retrieval can return grounded snippets without fetching source items from the provider during each chat turn.
For providers where the mode is user-selectable, live-only mode avoids embedding sync and indexed artifact retention.
Some connectors support both modes, but not every provider exposes both in the current runtime.
Google Drive and OneDrive use live for provider-backed document content search through file-resource-live-query and for browse/list flows through connector-resource-list.
Google Calendar and Microsoft Calendar are live-only for storage and do not create indexed calendar copies.
Google Contacts and Microsoft Contacts are live-only for storage and do not create indexed contact copies.
SharePoint and OneNote are live-only for storage and do not create indexed knowledge, file, or list copies.
Odoo is live-only for storage and does not create indexed business-record copies.

Lifecycle Summary

A user links or chooses a provider account in the shared connector setup flow for OAuth connectors, enters their own credential for user-managed API-key/PAT connectors, or chooses a deployment connector whose CMS credential profile is already valid.
The Connectors page groups linked OAuth accounts by provider, shows user-managed connectors as user-owned rows, and shows deployment connectors without a linked-account selector.
The system stores connector connection state, validates auth scopes for OAuth connectors, encrypts user-managed credentials in API-owned storage, enforces linked-account or owner-scoped credential ownership, and checks credential-profile readiness for deployment API-key connectors.
If indexed mode is enabled, sync jobs run through API queueing and Meltano-backed ingestion.
Retrieval uses live provider access, indexed data, or both depending on provider capability and connector mode.
If provider auth drifts, the system moves toward reauthorize, reconnect, credential setup, or retry guidance.
Disconnect triggers async cleanup and status transitions.
Deleting a linked OAuth account from an account row removes the provider account and schedules every connector under that account through the same async disconnect cleanup path. Deployment API-key rotation happens in the customer CMS and does not require existing users to reconnect.

Current Web UX Model

/connectors owns the page shell and uses the app shell action, toolbar, and overlay slots consistently with the rest of the web app.
The provider summary is an icon-first rail. Counts and issue indicators stay compact, with provider/account details shown in the grouped list rather than repeated around every logo.
Provider groups contain linked account groups. Account-scoped actions open the same reusable connector create modal with provider/account context already selected.
Linked OAuth account rows include account-level management. Deleting an OAuth account is a confirmed destructive action; it removes that linked account and disconnects all connectors under it. Better Auth final-account and stale-session checks block before new cleanup is scheduled. When the app needs fresh verification, it asks the user to verify with the same web sign-in method used by the current session, then reopens the destructive confirmation. Email/password verification stays on the Connectors page and uses the same full-width password input and show/hide password control as the main sign-in form. Older active sessions may recover without sign-out: credential accounts can verify with email/password, and if the account lookup is unavailable the same password proof can be attempted when email/password is allowed; SSO recovery is used only when there is exactly one configured workforce SSO account and no credential account. Workforce SSO and email/password sign-in accounts are not managed from this connector surface.
The connected connector row still shows identity, account/provider details, resource types, chat readiness, sync timing, retry state, source details, synced/indexed metrics when indexing is enabled, and lifecycle actions. Each row shows one primary action and moves secondary actions into an overflow menu so controls do not wrap on small screens.
Live-only connector rows do not show indexed-sync counters. When indexed metrics are shown, the nearby info disclosure explains that Synced means provider items observed by sync and Indexed means searchable embedded items after eligibility, extraction, permissions, and embedding finish.
Connectors needing attention sort before healthy connectors and can be filtered with the status chips.
The shared create modal is provider-first: generic launches open an auto-focused command-palette provider chooser, then the next focused level shows account-plus-connector rows for OAuth providers or direct connector rows for user-managed and deployment API-key providers. OAuth account choice should not be a dropdown-only field, and refresh controls stay out of the primary user path.
The chat composer + menu can open the shared connector create modal. It does not add a new connector to a locked chat focus; when focus is editable, the modal can offer an explicit “Use in this chat” action after creation.

Resource And Scope Rules

defaultResourceTypes and resourceSelectionPolicy come from the shared domain/runtime connector registry and are exposed in catalog/config contracts.
connectionScope also comes from the shared registry and is exposed in catalog/config contracts. Account-scoped connectors can be added once per linked OAuth account; configuration-scoped connectors include specific config keys, such as Jira siteId, in their persisted duplicate-prevention identity; deployment-scoped connectors derive a stable deployment account identity such as deployment:odoo.
Omitted resourceTypes default to defaultResourceTypes; empty resource arrays fail closed at the contract/service boundary.
Single-resource connectors keep that resource selected and do not render a toggle that can be turned off.
Multi-resource connectors can choose resources, but the final selected resource cannot be cleared.
Scoped resource controls are hidden for policy none, shown only when selectable for optional, and required for required.
Some connectors declare specific required scoped resource types. SharePoint requires selected sites, OneNote requires selected notebooks, Confluence requires selected spaces, and Jira requires selected projects; dependent pickers such as SharePoint lists/drives/folders or OneNote sections load through shared provider options from the current draft resource selection.
Provider-family resource scopes are separate from connector-level scoped selection. They are registered only when sibling connector keys safely share one upstream resource boundary, such as GitHub repositories. Microsoft connectors do not infer a shared account-level resource scope merely because they use the same microsoft OAuth provider.
Persisted connector enable/disable is not implemented yet. Disconnect/delete is the removal path until API, live-access, sync, Meltano, and cleanup semantics are designed.

How Connectors Depend On Auth

Connectors depend on auth for user identity and provider credential handling, but connector OAuth is not the same thing as workforce SSO. Platform sign-in proves who the user is; connector authorization or deployment credential setup grants access to external data sources. Deployment API-key connectors never attempt a Better Auth OAuth token exchange.

Meltano, Qdrant, And Provider Credentials

Meltano powers the indexed sync path.
Qdrant stores vector data, extracted chunk text, and permission/provenance payloads for indexed retrieval.
Provider credentials and tokens remain part of the connector auth boundary, not the workforce SSO boundary.
User-managed API-key/PAT credentials are entered in the web app, validated by API, and stored encrypted in API-owned persistence with key material supplied by deployment secrets.
Deployment API-key credentials are entered in customer CMS but are not stored in Payload or MongoDB. Production writes declared credential slots to Kubernetes Secret storage, and API reads mounted Secret files through the shared resolver. Local development uses the same CMS flow backed by gitignored files under env/cms-customer/connector-credentials/.
Sync workers resolve fresh provider access through API/auth token-context exchange; they do not refresh OAuth tokens directly.
Jira does not use Meltano or embeddings; it is live-only work-item access.
Odoo does not use Meltano or embeddings; it is live-only business-record access.
Calendar connectors do not use Meltano or embeddings; calendar-event data is transient live grounding only.
Contact connectors do not use Meltano or embeddings; contact/person data is transient live grounding only.
SharePoint and OneNote do not use Meltano or embeddings; Microsoft Graph page/list/file evidence is transient live grounding only.

Which Files Matter

File	What it helps you answer
`packages/domain/src/connectors/connectorRegistry.ts`	Connector keys, auth strategies, credential profiles, modes, and resources
`packages/connector-credentials/src/index.ts`	Shared credential secret-store contract, local/mounted readers, and redaction
`apps/api/src/connectors/connectorRuntimeExtensions.ts`	Runtime indexed/live/resource-list/smoke support
`apps/api/src/connectors/providerManifests.ts`	Provider manifests for live/indexed/config/eval/smoke hooks
`apps/api/src/connectors/credentials/connectorCredentialResolver.ts`	API credential-profile resolver for deployment API-key adapters
`apps/api/src/ingestion/connectorEmbeddingIngestionService.ts`	Indexed ingestion, dedupe, vector upsert, and cleanup path
`apps/api/src/ingestion/qdrantUpsertPayload.ts`	Qdrant point payload shape with chunk text and metadata
`packages/contracts/src/connectors/contracts.ts`	Connector public contracts, recovery states, and mode fields
`apps/web/app/pages/connectors.vue`	Provider/account grouped Connectors page shell and filters
`apps/web/app/components/connectors/ConnectorCreateModal.vue`	Shared connector create modal used by Connectors and chat
`apps/api/.env.example`	Connector runtime env groups and queue/storage settings
`infra/helm/customer-cluster/`	Customer-cluster Secret mount and least-privilege CMS RBAC
`docs/features/connectors/spec.md`	Full lifecycle, recovery, and rollout constraints
`docs/features/ingestion/spec.md`	Indexed sync, embedding, and ingestion runtime requirements
`docs/features/governance/spec.md`	Connector policy, registry, and secret-boundary requirements
`docs/features/realtime/spec.md`	Feathers realtime transport and connector status event rules
`docs/features/live-query/spec.md`	Live-query domains, retrieval precedence, and source policy