Technical docs
Integrations
Overview
Support reference for the OAuth integration flow used by AI teammate Connectors.
Current scope
- OAuth integrations are now employee-scoped inside an organization.
- The current frontend flow is launched from an AI teammate's `Connectors` tab, not from a standalone `/integrations` page.
- Google OAuth is used by predefined OAuth MCPs for:
- `gmail`
- `google_calendar`
- `google_drive`
Current frontend flow
- Connectors tab actions can include:
- `Connect`
- `Validate`
- `Reconnect`
- `Disconnect`
- The auth-link request includes the target teammate as query param:
- `employee_id`
- The OAuth callback route is still:
- `/integrations/[service]/callback`
- The callback page expects:
- `code`
- `state`
- optional `error`
- `state` is base64-encoded JSON and currently carries:
- `employeeId`
- On success, the callback finalizes the connection and redirects back to:
- `/staff/ai/{employee_id}?tab=mcps`
- Callback phases shown in the UI are:
- `Connecting integration...`
- `Integration connected`
- `Failed to connect integration`
Current API routes
- `GET /api/organizations/{organization_id}/integrations/{service}/auth_link`
- requires `employee_id`
- `POST /api/organizations/{organization_id}/integrations/{service}/callback`
- requires `code`
- requires `state`
- `GET /api/organizations/{organization_id}/employees/{employee_id}/integrations`
- `POST /api/organizations/{organization_id}/employees/{employee_id}/integrations/{service}/validate`
- `DELETE /api/organizations/{organization_id}/employees/{employee_id}/integrations/{service}`
Backend and permission notes
- All integration routes require authenticated organization access.
- Stored integration records are scoped by:
- organization
- employee
- service
- Current service enum supports only `google`.
- Validation returns the updated record plus `is_valid`.
Relationship to MCPs
- OAuth MCP runtime lookup now resolves the integration by the current AI teammate's `employee_id` and required OAuth service.
- If the teammate-specific integration does not exist, the OAuth MCP is unavailable at runtime.
- The AI teammate Connectors tab keeps OAuth MCP checkboxes disabled until the corresponding service connection exists for that teammate.