features oauth

OAuth

Active contributors: Mario Zechner, kt, Armin Ronacher

Purpose

Prime Agent supports OAuth-based provider authentication for model providers (Anthropic Claude Pro/Max, GitHub Copilot, OpenAI Codex) and for MCP servers. The ai package owns the OAuth provider interface, the PKCE utilities, the local callback-page server, and a provider registry; the coding-agent package stores the resulting credentials in auth.json and refreshes them under file lock; the web app exposes the flow through an HTTP endpoint that drives the same provider callbacks.

The shared abstractions let one credential lifecycle (login, token refresh, getApiKey) serve both model providers and MCP servers, with the provider id naming the credential key.

How it works

The provider interface and registry

packages/ai/src/utils/oauth/types.ts defines the contract. OAuthProviderInterface exposes id, name, login(callbacks), refreshToken(credentials), and getApiKey(credentials), plus optional usesCallbackServer, onManualCodeInput support, and modifyModels. OAuthLoginCallbacks carries onAuth, onPrompt, onProgress, onManualCodeInput, onSelect, and an AbortSignal.

packages/ai/src/utils/oauth/index.ts holds the registry: built-in providers (anthropicOAuthProvider, githubCopilotOAuthProvider, openaiCodexOAuthProvider) plus getOAuthProvider, registerOAuthProvider, unregisterOAuthProvider, resetOAuthProviders, getOAuthProviders, and getOAuthApiKey (which auto-refreshes expired tokens). packages/ai/src/oauth.ts re-exports the whole module as the public @earendil-works/pi-ai/oauth entry.

Provider implementations

• packages/ai/src/utils/oauth/anthropic.ts: authorization-code flow with PKCE against Claude's endpoints. It starts a Node callback server on port 53692, opens the authorize URL, and exchanges the code at the platform token endpoint. It supports pasting the redirect URL for a browser on another machine.
• packages/ai/src/utils/oauth/github-copilot.ts: device-code flow for GitHub Copilot. It requests a device code and user code, polls the access-token endpoint, then fetches a Copilot token whose proxy-ep field is converted into the API base URL.
• packages/ai/src/utils/oauth/openai-codex.ts: authorization-code flow with PKCE against auth.openai.com, using a local callback on http://localhost:1455/auth/callback. It decodes the returned JWT to extract the ChatGPT account id.
• packages/ai/src/utils/oauth/pkce.ts: generatePKCE produces a base64url code verifier and its SHA-256 challenge using Web Crypto, so it works in Node and browsers.
• packages/ai/src/utils/oauth/oauth-page.ts: oauthSuccessHtml and oauthErrorHtml render the browser page shown after a callback server receives the authorization response.

Credential storage

packages/coding-agent/src/core/auth-storage.ts stores credentials in ~/.prime/agent/auth.json (mode 0600). AuthStorage.login runs provider.login(callbacks) and persists the result as a { type: "oauth", ... } credential; getApiKey resolves the active credential, auto-refreshing an expired OAuth token under a file lock (refreshOAuthTokenWithLock), and falls back to env vars and other sources. logout removes the credential.

The web flow

web/app/src/routes/api/chat/providers/oauth.ts exposes POST /api/chat/providers/oauth. The handler handleChatProvidersOAuthPost (web/server/src/handlers/chat-providers-oauth.ts) creates an OAuthLoginSession, starts the provider login with callbacks that surface the auth URL and prompt state, and lets the client poll, continue (answer a prompt), or cancel the login. On success it reloads auth so new providers appear. Login sessions expire after 16 minutes.

sequenceDiagram
    participant U as User
    participant W as Web client
    participant S as web/server (OAuth login session)
    participant P as OAuth provider (ai/oauth)
    participant C as Callback server (localhost)
    participant A as Auth provider
    participant F as auth.json (AuthStorage)

    U->>W: sign in with provider
    W->>S: POST /api/chat/providers/oauth
    S->>P: login(callbacks)
    P->>P: generatePKCE() / device code
    P-->>S: onAuth(url, instructions)
    S-->>W: authUrl
    U->>W: open authUrl
    W->>A: redirect with code
    A->>C: redirect callback (code, state)
    C-->>P: resolve code
    P->>A: exchange code for tokens
    A-->>P: access + refresh tokens
    P->>S: return credentials
    S->>F: AuthStorage.login persists mcp:/provider credential
    S-->>W: success + providers
    W->>W: reload auth, use API key

Loading

Integration points

• The same provider registry and callback pattern back the MCP OAuth flow; see MCP.
• The web endpoint drives AuthStorage.login through getPrimeConfig().authStorage (web/server/src/prime-config.ts).
• Provider login display names are wired into /login UI via packages/coding-agent/src/core/provider-display-names.ts.

Entry points for modification

• Add or change a provider implementation: packages/ai/src/utils/oauth/ (anthropic.ts, github-copilot.ts, openai-codex.ts).
• Change PKCE or the callback page: packages/ai/src/utils/oauth/pkce.ts, packages/ai/src/utils/oauth/oauth-page.ts.
• Change credential persistence or refresh: packages/coding-agent/src/core/auth-storage.ts.
• Change the web login lifecycle: web/server/src/handlers/chat-providers-oauth.ts.

Key source files

File	Purpose
packages/ai/src/utils/oauth/types.ts	OAuthProviderInterface, OAuthLoginCallbacks, OAuthCredentials
packages/ai/src/utils/oauth/index.ts	Provider registry and high-level getOAuthApiKey
packages/ai/src/utils/oauth/anthropic.ts	Anthropic authorization-code + PKCE flow
packages/ai/src/utils/oauth/github-copilot.ts	GitHub Copilot device-code flow
packages/ai/src/utils/oauth/openai-codex.ts	OpenAI Codex authorization-code + PKCE flow
packages/ai/src/utils/oauth/pkce.ts	generatePKCE code verifier and challenge
packages/ai/src/utils/oauth/oauth-page.ts	Browser success/error callback pages
packages/ai/src/oauth.ts	Public @earendil-works/pi-ai/oauth entry
packages/coding-agent/src/core/auth-storage.ts	AuthStorage credential persistence and refresh
web/server/src/handlers/chat-providers-oauth.ts	handleChatProvidersOAuthPost web login lifecycle
web/app/src/routes/api/chat/providers/oauth.ts	Web POST /api/chat/providers/oauth route

Related pages

• The packages behind these features, LLM provider abstraction and streaming, Web app
• MCP - the MCP server OAuth flow that reuses the same machinery
• Slash commands - /login and /logout surfaces
• Features lens index, Glossary
• HTTP endpoint reference - the providers/oauth route