Description
Connected Importer Accounts give users a settings workflow for authorizing external services before creating imports. OAuth-capable providers open a managed consent link, while API-key providers use the gateway’s credential collection flow. Dots stores a connected-account reference and gateway source, not the provider’s raw token, then uses that reference to proxy adapter requests with credentials injected server-side.
The same lifecycle covers discovery, status, refresh, history, and revocation. The web settings surface lists active and prior connections, explains gateway availability, launches provider selection, handles the callback return, and lets a user revoke access. Server-side company scoping ensures a connection can only be resolved by its owning workspace.
Selling Points
- Connect without copying sensitive tokens into Dots. Provider credentials remain in the gateway and are injected only when an adapter makes an upstream request.
- One settings workflow covers different auth styles. OAuth consent and API-key collection share a consistent connection record and lifecycle.
- Workspace isolation is built in. A company-scoped lookup prevents one tenant from resolving another tenant’s connected account.
- Revocation is operational, not cosmetic. Removing a connection also drops the corresponding gateway account and updates visible status.
- Connection health stays observable. Periodic verification can mark expired accounts so failed imports have a clear remediation path.
User Story
A workspace owner wants to import a Notion database. They open Integrations, choose Notion, complete the provider’s consent flow in a new tab, and return to a refreshed connections list showing the account as active. They can now select resources for a sync binding, and later revoke that same connection from settings without hunting for stored secrets.
Extension Surface
This feature is configurable: users choose a provider, may supply a personal gateway project key, and manage connection state through settings, but they do not register new auth mechanisms from the UI. The configurable lifecycle is implemented in apps/web/src/modules/shell/settings/tabs/integrations/IntegrationsTab.tsx, while packages/connectors/src/services/connection-service.ts resolves the chosen gateway source and connected-account reference. Adding a new provider still requires connector and composition code, so the account surface itself is not the pluggable boundary.
Capabilities & Limits
Capabilities include provider discovery, connect-link initiation, callback completion, active/history views, status refresh, and revocation. Connections remember whether they belong to a deployment or personal gateway project, preventing accidental cross-project fallback.
The honest limit is dependence on a correctly configured gateway and provider auth configuration. If neither a deployment nor personal project key is available, connection initiation is unavailable rather than silently degrading. A connection authorizes access but does not itself import anything; the user must still create a binding to a specific source resource and target Dotabase.
Implementation Map
packages/connectors/src/services/connection-service.tspackages/api/src/routes/connectors.tsapps/web/src/modules/shell/settings/tabs/integrations/IntegrationsTab.tsxapps/web/src/modules/shell/settings/tabs/integrations/integrations-client.ts