-
Notifications
You must be signed in to change notification settings - Fork 0
OAuth and Codex
OBEY API Gateway supports browser-based OpenAI authentication and Codex backend translation, enabling use of your ChatGPT Plus/Pro subscription through the gateway.
Instead of manually creating and managing OpenAI API keys, authenticate with your ChatGPT subscription via browser-based OAuth.
providers:
- name: "openai-oauth"
type: "openai"
base_url: "https://api.openai.com/v1"
auth_method: "oauth" # Use OAuth instead of api_key_env# 1. Initiate browser-based login
curl -X POST http://localhost:8080/admin/oauth/openai/login
# 2. Browser opens to OpenAI's authorization page
# (user signs in with ChatGPT credentials)
# 3. Check session status
curl http://localhost:8080/admin/oauth/openai/status
# 4. Logout when needed
curl -X POST http://localhost:8080/admin/oauth/openai/logoutThe gateway handles the full token lifecycle automatically:
- Initiate — opens your default browser to OpenAI's authorization page
- Callback — receives the redirect on a local loopback server (port 1455)
- Exchange — trades the authorization code for tokens (PKCE + S256)
- Persist — encrypts and saves tokens to disk (survives restarts)
- Refresh — renews the access token in the background before expiry
- Failover — falls back to the next provider if the OAuth session expires
| Measure | Detail |
|---|---|
| Token encryption | AES-256-GCM at rest |
| Callback binding |
127.0.0.1 only (localhost) |
| Token logging | Values never logged at any level |
| PKCE flow | S256 challenge for authorization code exchange |
When using OAuth authentication, the gateway can transparently route requests through the ChatGPT Codex backend, translating between the Chat Completions API and the Responses API on the fly.
Client (Chat Completions API)
│
▼
┌─────────────────────┐
│ OBEY API Gateway │
│ │
│ Translate request: │
│ Chat Completions │
│ → Responses API │
└────────┬────────────┘
│
▼
┌─────────────────────┐
│ ChatGPT Codex │
│ Backend │
│ (Responses API) │
└────────┬────────────┘
│
▼
┌─────────────────────┐
│ OBEY API Gateway │
│ │
│ Translate response:│
│ Responses API │
│ → Chat Completions │
└────────┬────────────┘
│
▼
Client (standard response)
- Request: Chat Completions format → Responses API format
- Response: Responses API format → Chat Completions format
- Streaming: SSE events are translated on the fly
The gateway maintains an instructions store for Codex-capable providers. System instructions are managed separately and injected into Codex requests as needed.
Codex-capable providers can execute web search as a tool during a turn. When Codex Search is enabled, the gateway runs the search backend, feeds results back into the model's reasoning loop (up to max_iterations rounds), and — by default — also appends the results to the visible assistant message so they persist in chat history instead of living only in tool-call metadata that context compression can strip.
Codex Search defaults to enabled whenever a Codex provider is configured. Set enabled: false to turn it off explicitly.
codex_search:
enabled: true # Defaults to enabled when a Codex provider exists
output_to_chat: true # Append search results to the visible chat history (default: true)
base_url: "https://chatgpt.com/backend-api/codex/alpha/search"
timeout_seconds: 15 # Per-search timeout, 1–120 (default: 15)
max_iterations: 5 # Max search rounds per turn, 1–20 (default: 5)| Field | Default | Range | Purpose |
|---|---|---|---|
enabled |
enabled when a Codex provider exists | — | Master switch |
output_to_chat |
true |
— | Persist results in visible chat, not just tool metadata |
base_url |
ChatGPT Codex search endpoint | HTTP/HTTPS URL | Search backend URL |
timeout_seconds |
15 |
1–120 | Per-search timeout |
max_iterations |
5 |
1–20 | Max search rounds per turn |
Codex requests can carry reasoning parameters, including the xhigh effort level. Two allowlists let you extend which model identifiers accept these parameters beyond the built-in reasoning-model detection:
# Models that accept Codex `xhigh` reasoning effort
xhigh_models_allowlist:
- "my-custom-o-series-model"
# Models that accept Codex reasoning parameters at all
reasoning_models_allowlist:
- "my-custom-reasoning-model"See Reasoning Compatibility for how reasoning effort maps to per-family parameters during failover.
When running in Docker, the OAuth callback server needs to be reachable from the host browser:
# Already set in the official Dockerfile
ENV OAUTH_CALLBACK_BIND_HOST=0.0.0.0
EXPOSE 1455Map port 1455 when running the container:
docker run -d \
-p 8080:8080 \
-p 1455:1455 \
-v ai-gateway-data:/data \
obey-api-gatewayThe gateway tracks OpenAI rate-limit headers from OAuth provider responses:
- Displayed in the admin UI for usage visibility
- Used as fallback cooldown when no
Retry-Afterheader is present on 429 responses - Helps inform when you're approaching subscription limits
OAuth providers participate in the normal failover chain:
- If the OAuth token is valid → request routed through OAuth provider
- If the token expires or refresh fails → circuit breaker trips
- Gateway fails over to the next provider in the model group
This means you can configure OAuth as your primary provider with an API-key provider as fallback:
providers:
- name: "openai-oauth"
type: "openai"
base_url: "https://api.openai.com/v1"
auth_method: "oauth"
- name: "openai-api"
type: "openai"
base_url: "https://api.openai.com/v1"
api_key_env: "OPENAI_API_KEY"
model_groups:
- name: "gpt-4-group"
models:
- provider: "openai-oauth"
model: "gpt-4"
priority: 1 # Try OAuth first (free with subscription)
- provider: "openai-api"
model: "gpt-4"
priority: 2 # Fall back to API key- Security — token encryption and storage
- Providers — provider configuration
- Admin Panel & Dashboard — OAuth management UI