OpenAI Codex OAuth and API Key Setup

Use your ChatGPT plan with Codex OAuth: run codex login —device-auth and upload ~/.codex/auth.json. Or add an OpenAI API key. Agents never see either.

Overview

OneCLI injects your OpenAI credentials into requests to api.openai.com automatically. Agents make standard HTTP requests to the OpenAI API; the gateway adds the Authorization: Bearer header before forwarding.

This lets agents use GPT models, DALL-E, embeddings, and other OpenAI services without ever seeing or handling your credentials directly. For a comparison of supported LLM providers, see LLM Providers.

Auth methods

OneCLI supports two ways to authenticate with OpenAI:

Method	Best for	Credential
API Key	Pay-per-use API access	sk-proj-... from the OpenAI Dashboard
Codex (OAuth)	ChatGPT subscription users (Plus/Pro/Team)	auth.json from codex login

Setup: API Key

Use this method if you have an OpenAI API key with pay-per-use billing.

1. Get your API key

   Go to platform.openai.com/api-keys and create a new secret key. Copy it — you won’t be able to see it again.

2. Add the key in OneCLI

   Open the OneCLI dashboard, navigate to Connections > LLMs, and click Add LLM Key. Select OpenAI, make sure the API Key tab is selected, and paste your key.

CLI alternative:

onecli secrets create --name "OpenAI" --type openai \
  --value "$OPENAI_API_KEY" --host-pattern api.openai.com

Setup: Codex (OAuth)

Use this method to route requests through your ChatGPT subscription instead of paying per API call. This uses the same OAuth credentials that OpenAI Codex CLI uses.

1. Install Codex CLI

   npm install -g @openai/codex
   
2. Authenticate with device auth

   codex login --device-auth
   

   Follow the prompts to sign in with your ChatGPT account. Once authenticated, Codex saves your credentials to ~/.codex/auth.json.

   If you see “Please contact your workspace admin to enable device code authentication”, your ChatGPT workspace admin needs to turn on device code sign-in for Codex before you can continue.

3. Add the credentials in OneCLI

   Open the OneCLI dashboard, navigate to Connections > LLMs, and click Add LLM Key. Select OpenAI and switch to the Codex (OAuth) tab. The dialog shows the two steps: run codex login --device-auth (click the command to copy it), then upload the auth.json file it creates (~/.codex/auth.json).

   

   Once connected, an agent’s model list shows the models your ChatGPT login can use. Some API-only models are not available through a ChatGPT login.

CLI alternative:

onecli secrets create --name "Codex" --type openai \
  --file ~/.codex/auth.json --host-pattern api.openai.com

The gateway automatically refreshes the access token when it expires using the stored refresh token — no manual re-authentication needed.

How it works

1. Your credentials are encrypted and stored by OneCLI (AES-256-GCM at rest)
2. When an agent sends a request to api.openai.com, the gateway intercepts it
3. The gateway injects an Authorization: Bearer {token} header
4. The request is forwarded to OpenAI

For Codex OAuth, the gateway also monitors token expiry. When the access token expires, it automatically uses the refresh token to obtain a new one and persists the updated credentials — agents experience no interruption.

Agents never see the raw credentials. If you rotate your key or re-authenticate with Codex, update it in the dashboard and all agents pick up the new credentials automatically.

Controlling access

Access is per agent: attach the key to each agent that needs it — an agent without the grant can’t use it at all. Organization rules add guardrails on top: rate-limit requests, restrict agents to specific models by blocking certain paths, or flag high-cost operations for manual approval. Everything is checked before credential injection, so a blocked request never reaches OpenAI.