Codex CLI API Key Setup Guide 2026

Two Authentication Methods Compared

Before configuring anything, understand the differences and pick the right method for your situation:

Method 1: ChatGPT Account Login

If you have a ChatGPT Plus, Pro, Business, Edu, or Enterprise subscription, you can authenticate directly with your account — no separate API Key management required.

Login steps

# Start the OAuth flow
$ codex login

After running the command, Codex CLI will:

1. Print an authorization URL and attempt to open it in your browser automatically
2. Your browser opens the ChatGPT OAuth authorization page
3. Log in with your ChatGPT account and click "Authorize"
4. The browser redirects back to a local callback URL; the terminal shows login success

After successful login, the auth token is saved to ~/.codex/auth.json — you won't need to log in again on subsequent codex runs.

Verifying login

# Launch codex and check the status indicator in the bottom-left
$ codex
# "● connected" in the status bar means authentication succeeded

# Or inspect the auth file directly (key is partially masked)
$ cat ~/.codex/auth.json

Method 2: OpenAI API Key

The API Key method is more flexible — no ChatGPT subscription required, fine-grained cost control, and support for per-project keys via environment variables.

Where to get an API Key

OpenAI API Keys are managed at platform.openai.com/api-keys:

1. Log in to platform.openai.com
2. Click "API keys" in the left sidebar
3. Click "Create new secret key"
4. Give the key a descriptive name (e.g. "codex-cli-dev") for easier management later
5. Copy the key immediately — it is shown only once. After closing the dialog, you cannot view the full key again

Setting up your API Key

Two ways to configure the API Key with Codex CLI:

Option 1: via codex login command (recommended)

$ codex login --with-api-key
# The CLI prompts you to paste your API Key
# The key is stored (encrypted) in ~/.codex/auth.json

Option 2: via environment variable

# Temporary — applies only to the current shell session
$ export OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx
$ codex "test connection"

To make it permanent, add it to your shell config file (~/.zshrc or ~/.bashrc):

# Open the file in an editor
$ nano ~/.zshrc

# Add this line at the end (replace with your actual key):
export OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx

# Reload the config
$ source ~/.zshrc

Multi-Account / Multi-Key Management

If you need different API Keys for different projects (e.g. personal vs. work accounts), here are your options:

Where credentials are stored

Codex CLI stores the current active credential in ~/.codex/auth.json. You can inspect it (the key value is partially masked):

$ cat ~/.codex/auth.json
# Outputs something like: {"type":"api-key","key":"sk-proj-xxx...xxx"}

Switching accounts

Re-run the appropriate codex login command to switch. The new credential overwrites the existing auth.json:

# Switch to ChatGPT OAuth login
$ codex login

# Switch to API Key
$ codex login --with-api-key

# Log out (removes stored credentials)
$ codex logout
# Or manually
$ rm ~/.codex/auth.json

Per-project API Keys with direnv

direnv is the cleanest solution for using different API Keys in different projects — it automatically loads environment variables when you enter a directory and unloads them when you leave:

# Install direnv (macOS)
$ brew install direnv

# Add the hook to your shell config (zsh example)
$ echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
$ source ~/.zshrc

# In your project directory, create a .envrc file (DO NOT commit this!)
$ cd /path/to/your/project
$ echo 'export OPENAI_API_KEY=sk-proj-work-account-key' > .envrc
$ direnv allow .

# Make sure .envrc is in .gitignore
$ echo '.envrc' >> .gitignore

From now on, entering this directory automatically switches OPENAI_API_KEY to the project-specific key. Leaving the directory restores your global setting.

API Key Security Best Practices

A leaked API Key gives anyone unlimited access to your OpenAI balance. Build these habits from the start:

Never commit keys to a repository

• Never run git add .env or any file containing an API Key
• Add protection rules to every project's .gitignore: .env, .env.local, .envrc
• Consider using gitleaks to scan commit history for leaked secrets

# API keys and environment variable files
.env
.env.*
.envrc
*.key
*_secret*

Set API spending limits

At platform.openai.com/settings/organization/limits, configure spending controls:

• Monthly budget: API calls return 429 after the monthly cap is reached
• Usage alerts: Email notification when spending crosses a threshold

For individual developers, a monthly cap of $5–$20 provides good protection against accidental overuse.

How to immediately revoke a leaked key

If you suspect your API Key has been leaked (e.g., accidentally pushed to a public GitHub repo), act immediately:

1. Log in to platform.openai.com/api-keys
2. Find the compromised key and click "Revoke" — it is invalidated instantly
3. Create a new key and update your local configuration
4. If committed to GitHub, check if GitHub's secret scanning already flagged it — GitHub auto-notifies OpenAI of exposed keys which may trigger auto-revocation
5. Optionally rewrite Git history with BFG Repo Cleaner or git filter-branch to remove the key from commit history

# After revoking the old key, log in with the new one
$ codex login --with-api-key
# Paste your new API Key when prompted

Common Authentication Errors

401 Unauthorized

Meaning: The API Key is invalid, has been revoked, or is missing.

Fix:

• Verify OPENAI_API_KEY is correctly set (no extra spaces or newlines)
• Confirm the key's status shows as Active at platform.openai.com/api-keys
• If using codex login --with-api-key, re-run it and paste the key again

# Check that the env var is set (won't display the full key)
$ echo ${OPENAI_API_KEY:0:10}...
# Should print: sk-proj-xx...

# Test the key directly with curl
$ curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -s | head -c 200

403 Forbidden: Geographic restriction

Meaning: The API request came from a region where OpenAI service is not available.

Fix: Configure HTTPS_PROXY to route the API request through a proxy server in a supported region:

$ export HTTPS_PROXY=http://127.0.0.1:7890
$ codex "test connection"

See the Proxy / China Guide for full configuration details.

Authentication required

Meaning: Codex CLI cannot find any valid credentials — you haven't completed authentication.

Fix: Run codex login (for ChatGPT OAuth) or codex login --with-api-key (for API Key) to complete authentication, then retry.

Insufficient quota / Rate limit exceeded

Meaning: Your account has hit its monthly spending cap, or you've exceeded rate limits.

Fix: Check your usage and billing at platform.openai.com/usage. If you hit the monthly budget limit, increase it or wait until the next billing cycle. For rate limits, add delays between requests or upgrade to a higher usage tier.

FAQ