Skip to content
AlumiaDocs

Search docs

Find pages, headings, and concepts. Press ⌘K or Ctrl+K to toggle.

OAuth flow

How OAuth connections work in Alumia and how the chat resumes after consent.

Open in ChatGPTOpen in Claude

OAuth-backed connectors hand the user off to the provider, then bring them back to a callback page that signals completion to the originating UI.

Flow

  1. The user clicks the connect button for a connector on /[orgSlug]/connectors (or inside a chat card when an agent requests access).
  2. The platform opens the provider's authorization URL in a normal new tab, not a popup. No fixed width/height/popup=1 features.
  3. The user grants consent at the provider.
  4. The provider redirects to /auth/connector-callback with oauth_result, oauth_message, and connection_id query params.
  5. The callback page broadcasts the result, then closes itself.
  6. The originating page picks up the broadcast and resumes the chat session that was waiting on the connection.

How resumption is delivered

The callback page (packages/web/app/(auth)/auth/connector-callback/page.tsx) emits the result through three independent channels so it works across browser configurations:

ChannelUsed when
BroadcastChannel("alumia-connector-oauth")Same-origin tabs in modern browsers.
localStorage key alumia:connector-oauthStorage events for tabs without BroadcastChannel.
window.opener.postMessageTabs opened with window.open that retain an opener reference.

The chat card listens on all three and also polls connection status as a fallback. After the result arrives, the queued chat message that triggered the connect prompt is re-issued automatically.

What never happens

  • The callback never sends tokens or secrets back through postMessage or localStorage. It carries result, connectionId, and an optional human-readable message only.
  • The provider window never inherits the chat's auth — only the platform's own callback resolves the connection.
  • The connect button never relies solely on window.opener; if the opener is gone, polling resolves the chat.

Disconnecting

Removing a connection at /[orgSlug]/connectors revokes the stored credentials immediately. Sessions that try to use the connector after that point receive a tool error and surface a reconnect prompt.