docs/platform/contributing/oauth-integration-flow.md
The AutoGPT platform implements OAuth 2.0 in two distinct contexts:
This document focuses on the API Integration OAuth flow used for connecting to external services. For the list of supported providers, see /backend/backend/integrations/providers.py. For user authentication documentation, see the Supabase auth implementation.
CredentialsInput component (/frontend/src/components/integrations/credentials-input.tsx)/frontend/src/app/(platform)/auth/integrations/oauth_callback/route.ts)/backend/backend/api/features/integrations/router.py)/backend/backend/integrations/oauth/)/backend/backend/integrations/credentials_store.py)/auth/integrations/oauth_callbackcode and state parameters from provider/api/integrationsGET /{provider}/login - Initiates OAuth flowPOST /{provider}/callback - Exchanges auth code for tokensGET /credentials - Lists user credentialsDELETE /{provider}/credentials/{id} - Revokes credentialsget_login_url() - Constructs provider authorization URLexchange_code_for_tokens() - Exchanges auth code for access tokensrefresh_tokens() - Refreshes expired access tokensrevoke_tokens() - Revokes tokens at providersequenceDiagram
participant User
participant Frontend
participant Backend
participant Redis
participant Provider
User->>Frontend: Click "Sign in with Provider"
Frontend->>Backend: GET /api/integrations/{provider}/login
Backend->>Redis: Store state token + code verifier
Backend->>Frontend: Return login URL + state token
Frontend->>Frontend: Open popup window
Frontend->>Provider: Redirect to authorization URL
sequenceDiagram
participant User
participant Provider
participant Callback
participant Frontend
participant Backend
User->>Provider: Authorize application
Provider->>Callback: Redirect with code + state
Callback->>Frontend: PostMessage with code + state
Frontend->>Backend: POST /api/integrations/{provider}/callback
Backend->>Provider: Exchange code for tokens
Provider->>Backend: Return access + refresh tokens
Backend->>Backend: Store credentials
Backend->>Frontend: Return credential metadata
sequenceDiagram
participant Application
participant Backend
participant Provider
Application->>Backend: Request with credential ID
Backend->>Backend: Check token expiry
Backend->>Provider: POST refresh token
Provider->>Backend: Return new tokens
Backend->>Backend: Update stored credentials
Backend->>Application: Return valid access token
graph TB
subgraph "OAuth Use Cases"
subgraph "User SSO Login"
LP[Login Page]
SB[Supabase Auth]
GO[Google OAuth SSO]
SC[Session Cookies]
end
subgraph "API Integration OAuth"
UI[CredentialsInput Component]
CB[OAuth Callback Route]
PW[Popup Window]
end
end
subgraph "Backend API (Trusted)"
subgraph "Auth Management"
SA[Supabase Client]
UM[User Management]
end
subgraph "Integration Management"
IR[Integration Router]
OH[OAuth Handlers]
CS[Credentials Store]
CM[Credentials Manager]
end
end
subgraph "Storage"
RD[(Redis)]
PG[(PostgreSQL)]
SDB[(Supabase DB)]
end
subgraph "External Providers"
GH[GitHub OAuth]
GL[Google APIs OAuth]
NT[Notion OAuth]
OT[...Other Providers]
end
%% User Login Flow
LP -->|Login with Google| SB
SB -->|OAuth Request| GO
GO -->|User Auth| SB
SB -->|Session| SC
SB -->|User Data| SDB
%% API Integration Flow
UI -->|1. Initiate OAuth| IR
IR -->|2. Generate State| RD
IR -->|3. Return Auth URL| UI
UI -->|4. Open Popup| PW
PW -->|5. Redirect| GH
GH -->|6. Auth Code| CB
CB -->|7. PostMessage| UI
UI -->|8. Send Code| IR
IR -->|9. Exchange Code| OH
OH -->|10. Get Tokens| GH
OH -->|11. Store Creds| CS
CS -->|12. Save| PG
OH -.->|Token Refresh| GL
OH -.->|Token Refresh| NT
OH -.->|Token Refresh| OT
graph LR
subgraph "Data Types"
ST[State Token]
CV[Code Verifier]
CC[Code Challenge]
AC[Auth Code]
AT[Access Token]
RT[Refresh Token]
end
subgraph "Frontend Flow"
U1[User Initiates]
U2[Receives State]
U3[Opens Popup]
U4[Receives Code]
U5[Sends to Backend]
end
subgraph "Backend Flow"
B1[Generate State]
B2[Store in Redis]
B3[Validate State]
B4[Exchange Code]
B5[Store Credentials]
end
U1 --> B1
B1 --> ST
B1 --> CV
CV --> CC
B2 --> U2
U3 --> AC
AC --> U4
U5 --> B3
B3 --> B4
B4 --> AT
B4 --> RT
AT --> B5
RT --> B5
graph TB
subgraph "Security Layers"
subgraph "Transport Security"
HTTPS[HTTPS Only]
CSP[Content Security Policy]
end
subgraph "Authentication"
JWT[JWT Tokens]
STATE[CSRF State Tokens]
PKCE[PKCE Challenge]
end
subgraph "Storage Security"
ENC[Encrypted Credentials]
SEC[SecretStr Type]
MUTEX[Redis Mutex Locks]
end
subgraph "Access Control"
USER[User Scoped]
SCOPE[OAuth Scopes]
EXPIRE[Token Expiration]
end
end
HTTPS --> JWT
JWT --> USER
STATE --> PKCE
PKCE --> ENC
ENC --> SEC
SEC --> MUTEX
USER --> SCOPE
SCOPE --> EXPIRE
stateDiagram-v2
[*] --> Initiated: User clicks sign-in
Initiated --> Authorizing: Popup opened
Authorizing --> Authorized: User approves
Authorizing --> Failed: User denies
Authorized --> Active: Tokens stored
Active --> Refreshing: Token expires
Refreshing --> Active: Token refreshed
Refreshing --> Expired: Refresh fails
Active --> Revoked: User deletes
Failed --> [*]
Expired --> [*]
Revoked --> [*]
note right of Active: Credentials can be used
note right of Refreshing: Automatic process
note right of Revoked: Tokens revoked at provider
/login → Supabase OAuth → /auth/callback/backend/backend/integrations/providers.py/backend/backend/integrations/oauth//api/integrations/{provider}/login → /auth/integrations/oauth_callbacksecrets.token_urlsafe()secrets.compare_digest()secrets.token_urlsafe(128) (approximately 171 characters when base64url encoded, though RFC 7636 recommends 43-128 characters)Structure:
OAuth2Credentials:
- id: UUID
- provider: ProviderName
- access_token: SecretStr (encrypted)
- refresh_token: Optional[SecretStr]
- scopes: List[str]
- expires_at: Optional[int]
- username: Optional[str]
Persistence: PostgreSQL via Prisma ORM
Access Control: User-scoped with mutex locking
SecretStr typeThe platform supports various OAuth providers including GitHub, Google, Notion, Twitter, and others. For the complete list, see:
/backend/backend/integrations/providers.py - All supported providers/backend/backend/integrations/oauth/ - OAuth implementationsEach provider handler implements the security measures defined in BaseOAuthHandler, ensuring consistent token management and refresh logic across all integrations.
{
"detail": {
"message": "Human-readable error description",
"hint": "Actionable suggestion for resolution"
}
}