Integrations

Support reference for the OAuth integration flow used by AI teammate Connectors.

• 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`
• Google authorization requests Gmail read, labels, compose, and modify access. The modify scope lets the Gmail connector change message state, including marking messages as read.
• Microsoft OAuth is used by predefined OAuth MCPs for:
• `outlook_mail`
• `outlook_calendar`
• `onedrive`
• The Microsoft integration requests Graph scopes for mail read, mail read-write, mail send, calendar read-write, files read-all, and general file read-write access, plus offline access and basic profile info.
• Microsoft connections authorized before the general file read-write scope was added may need `Reconnect` so the user can consent to the expanded permission before file-write operations work.

• 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`

• `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}`

• All integration routes require authenticated organization access.
• Stored integration records are scoped by:
• organization
• employee
• service
• Current service enum supports `google` and `microsoft`.
• Validation returns the updated record plus `is_valid`.
• Microsoft tokens are validated by probing the Graph `me` endpoint with the stored access token; refresh exchanges use the Microsoft token endpoint and preserve the existing refresh token when a refresh response omits a new one.

• 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.
• Connecting or reconnecting a provider automatically assigns every OAuth MCP served by that provider to the AI teammate. Google assigns Gmail, Google Calendar, and Google Drive; Microsoft assigns Outlook Mail, Outlook Calendar, and OneDrive. Existing assignments are left in place without duplication.
• Disconnecting removes the stored integration and all matching provider OAuth MCP assignments in one transaction. If assignment cleanup fails, the integration deletion is rolled back.
• The AI teammate Connectors tab keeps OAuth MCP checkboxes disabled until the corresponding service connection exists for that teammate. After connection, users can still change individual assignments.