OAuth Management

Manage ChatGPT account OAuth flows

Overview

The OAuth API manages the authentication flow for adding ChatGPT accounts to Codex-LB. It supports both browser-based PKCE flow and device code flow.

All OAuth endpoints require dashboard authentication. See Dashboard Auth for login details.

POST /api/oauth/start

Initiate an OAuth flow to add a new ChatGPT account.

Request Body

method · string · required

OAuth method to use. Options:

• "pkce" - Browser-based PKCE flow (recommended)
• "device_code" - Device code flow for headless environments

Response

method · string

The OAuth method being used ("pkce" or "device_code")

authorization_url · string

For PKCE: URL to redirect the user to for authorization

device_code · string

For device code: The device code to enter at the verification URL

user_code · string

For device code: User-friendly code to display

verification_url · string

For device code: URL where the user enters the code

expires_in · integer

For device code: Time in seconds until the code expires

interval · integer

For device code: Polling interval in seconds

Example Request

cURL

curl -X POST http://localhost:2455/api/oauth/start \
  -H "Content-Type: application/json" \
  -H "Cookie: dashboard_session=<session_id>" \
  -d '{"method": "pkce"}'

Example Response (PKCE)

{
  "method": "pkce",
  "authorization_url": "https://auth.openai.com/authorize?client_id=...&code_challenge=..."
}

Example Response (Device Code)

{
  "method": "device_code",
  "device_code": "NGU5OWM1YzQtMjExOC00...",
  "user_code": "ABCD-EFGH",
  "verification_url": "https://auth.openai.com/activate",
  "expires_in": 900,
  "interval": 5
}

GET /api/oauth/status

Check the status of an ongoing OAuth flow.

Response

status · string

Current OAuth status:

• "pending" - Waiting for user authorization
• "completed" - Authorization successful
• "failed" - Authorization failed
• "none" - No active OAuth flow

error · string

Error message if status is "failed"

Example Request

cURL

curl http://localhost:2455/api/oauth/status \
  -H "Cookie: dashboard_session=<session_id>"

Example Response

{
  "status": "pending"
}

POST /api/oauth/complete

Complete the OAuth flow and add the account.

Request Body

code · string

For PKCE: Authorization code from the callback

state · string

For PKCE: State parameter from the callback

Response

success · boolean

Whether the account was successfully added

account_id · string

ID of the newly created account

email · string

Email address associated with the account

Example Request

cURL

curl -X POST http://localhost:2455/api/oauth/complete \
  -H "Content-Type: application/json" \
  -H "Cookie: dashboard_session=<session_id>" \
  -d '{"code": "auth_code_here", "state": "state_here"}'

Example Response

{
  "success": true,
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[e-mail]"
}

Error Codes

Code	Status	Description
oauth_error	502	Upstream OAuth provider error
not_implemented	501	OAuth method not implemented
authentication_required	401	Dashboard session invalid or expired
authorization_pending	400	Authorization not yet completed
expired_token	400	Authorization code or device code expired

OAuth Flow Diagrams

PKCE Flow

Device Code Flow

Related

• Guides → Adding Accounts - Step-by-step guide for adding accounts
• Configuration → OAuth - OAuth configuration settings
• Dashboard Auth - Dashboard authentication