OAuth Management

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

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": "[email protected]"
}

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

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

Overview

OpenAI-Compatible Endpoints

Codex Endpoints

Management API

Overview

POST /api/oauth/start

Request Body

Response

Example Request

Example Response (PKCE)

Example Response (Device Code)

GET /api/oauth/status

Response

Example Request

Example Response

POST /api/oauth/complete

Request Body

Response

Example Request

Example Response

Error Codes

OAuth Flow Diagrams

PKCE Flow

Device Code Flow

Build docs developers (and LLMs) love

Overview

OpenAI-Compatible Endpoints

Codex Endpoints

Management API

​Overview

​POST /api/oauth/start

​Request Body

​Response

​Example Request

​Example Response (PKCE)

​Example Response (Device Code)

​GET /api/oauth/status

​Response

​Example Request

​Example Response

​POST /api/oauth/complete

​Request Body

​Response

​Example Request

​Example Response

​Error Codes

​OAuth Flow Diagrams

​PKCE Flow

​Device Code Flow

​Related

Build docs developers (and LLMs) love

Overview

POST /api/oauth/start

Request Body

Response

Example Request

Example Response (PKCE)

Example Response (Device Code)

GET /api/oauth/status

Response

Example Request

Example Response

POST /api/oauth/complete

Request Body

Response

Example Request

Example Response

Error Codes

OAuth Flow Diagrams

PKCE Flow

Device Code Flow

Related