Technical docs
Integrations
Overview
Support reference for OAuth integrations at `/integrations`.
What the page does
- Lets organization members connect external OAuth providers to their own account.
- Current provider list has one option: `Google`.
- Google OAuth is used by predefined OAuth MCPs for:
- `gmail`
- `google_calendar`
- `google_drive`
Current `/integrations` page behavior
- Page title: `Integrations`.
- Page description: `Connect external OAuth providers to your account.`
- Header action: `Refresh`.
- Each provider card shows:
- provider name
- description
- connection status badge when connected
- connected account ID when `oauth_user_id` is available
- Current Google description: `Connect Gmail, Calendar, and Drive with read-only access.`
Connection states and actions
- Disconnected state:
- primary action: `Connect`
- Connected state:
- status badge can show:
- `Valid`
- `Invalid`
- `Unknown`
- actions:
- `Validate`
- `Reconnect`
- `Disconnect`
- `Disconnect` asks for browser confirmation before removal.
- Failed loads show `Failed to load integrations` with `Retry`.
OAuth callback flow in the frontend
- Callback route: `/integrations/[service]/callback`
- Expected query params:
- `code`
- optional `error`
- The callback page has three phases:
- `Connecting integration…`
- `Integration connected`
- `Failed to connect integration`
- On success it shows a toast, then redirects back to `/integrations` after about `800ms`.
- On failure it shows `Back to integrations`.
Current API routes
- `GET /api/organizations/{organization_id}/integrations`
- `POST /api/organizations/{organization_id}/integrations/{service}`
- validates an existing stored OAuth connection
- `GET /api/organizations/{organization_id}/integrations/{service}/auth_link`
- `POST /api/organizations/{organization_id}/integrations/{service}/callback`
- `DELETE /api/organizations/{organization_id}/integrations/{service}`
Backend and permission notes
- All integrations routes require an authenticated user and organization access.
- Stored integration records are user-scoped inside the organization.
- Listing returns only records for the current user.
- Current service enum supports only `google`.
- Validation updates the stored status and returns `is_valid` plus the updated record.
Relationship to MCPs
- `/mcps` and AI teammate `Connectors` tabs use the integrations state to warn when a required OAuth provider is not connected.
- OAuth MCP warnings link users to `/integrations`.
- Disconnecting Google does not remove OAuth MCP definitions from the UI, but those MCPs will not work until Google is reconnected.