Codex API Key Setup Guide: Get, Configure, and Troubleshoot

Most developers prefer API Keys for calling AI services — they're flexible, programmable, and don't depend on browser logins. But when getting started with Codex, many tutorials only cover the ChatGPT username-and-password flow, leaving users confused about how API Keys work. This article explains both authentication methods and their differences, and shows how TeamoRouter's unified API Key approach simplifies everything.

Why Many Developers Prefer API Keys over ChatGPT Login

API Keys offer distinct advantages over ChatGPT account login:

• Programmability: CI/CD pipelines, scripts, and automated tasks can't use a browser login to call APIs.
• Usage-based billing: Know exactly how much each request costs, with no risk of subscription expiration.
• Multi-tool sharing: One API Key works across Codex CLI, ChatGPT App (custom endpoint), IDE plugins, and more.
• Team collaboration: Multiple developers share one billing pool for centralized management.

However, getting an API Key directly from OpenAI faces two real-world hurdles: international payment (requires a foreign credit card) and network restrictions from certain regions.

Two Authentication Methods: ChatGPT Login vs API Key

ChatGPT Login Method

codex
# Browser opens for OAuth authorization
# Codex automatically gets the access token after login

API Key Method

# Write ~/.codex/config.toml first (see "How to Configure the Base URL" below), then set the key and start
export OPENAI_API_KEY="sk-xxxxxxxxxxxx"

codex

Who API Key Suits

• Automation users: Integrating Codex into CI/CD, scripts, or batch jobs
• Teams: Multiple developers sharing one Key and billing pool
• Cross-tool users: Sharing API quota across Codex CLI, IDE plugins, and custom apps
• Cost control: Need precise usage-based billing without subscription lock-in

How to Configure Environment Variables

macOS / Linux

# Temporary (current terminal session)
export OPENAI_API_KEY="sk-teamo-xxxxxxxx"

# Permanent (write to shell profile)
echo 'export OPENAI_API_KEY="sk-teamo-xxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell

# Temporary
$env:OPENAI_API_KEY="sk-teamo-xxxxxxxx"

# Permanent (current user)
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-teamo-xxxxxxxx", "User")

Using a .env File (Recommended)

Create a .env file for project-level configuration:

OPENAI_API_KEY=sk-teamo-xxxxxxxx

Then load it in the terminal:

export $(cat .env | xargs)
codex

How to Configure the Base URL

Current Codex CLI does not read the OPENAI_BASE_URL environment variable; the API endpoint goes in the model_providers section of ~/.codex/config.toml. For users in restricted networks, point it at TeamoRouter:

macOS / Linux:

mkdir -p ~/.codex && cat > ~/.codex/config.toml <<'EOF'
model_provider = "teamorouter"
model = "gpt-6.1-sol"

[model_providers.teamorouter]
name = "TeamoRouter"
base_url = "https://api.teamorouter.vip/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
EOF

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "$HOME\.codex" | Out-Null
@'
model_provider = "teamorouter"
model = "gpt-6.1-sol"

[model_providers.teamorouter]
name = "TeamoRouter"
base_url = "https://api.teamorouter.vip/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
'@ | Set-Content -Path "$HOME\.codex\config.toml" -Encoding UTF8

Once config.toml is in place, you can also pass the key inline with the codex command:

OPENAI_API_KEY="sk-teamo-xxxxxxxx" codex

Note: Whether base_url should include /v1 depends on the tool's protocol implementation. Codex CLI uses the Responses API (/v1/responses), so base_url should include the /v1 path.

Common Errors and Troubleshooting

invalid API Key

Error: 401 Unauthorized
{
  "error": {
    "message": "Incorrect API key provided",
    "type": "invalid_request_error"
  }
}

Check:

• Verify the env var is set: echo $OPENAI_API_KEY
• Ensure no extra whitespace or newlines around the Key
• Confirm the API Key hasn't expired

insufficient balance

Error: 429 Too Many Requests
{
  "error": {
    "message": "You exceeded your current quota",
    "type": "insufficient_quota"
  }
}

Check:

• Log into the TeamoRouter console and check your balance
• Ensure the account linked to the API Key has sufficient credits

model no permission

Error: 403 Forbidden
{
  "error": {
    "message": "The model `gpt-6.1-sol` is not available for your API key",
    "type": "access_terminated"
  }
}

Check:

• Confirm the API Key has permission for the requested model
• Check the model authorization list in the TeamoRouter console

baseUrl misconfiguration

Error: 404 Not Found

Check:

• Verify base_url in ~/.codex/config.toml includes the /v1 path
• Ensure no trailing slash at the end of base_url

FAQ

Can I use the API credits that come with ChatGPT Plus?

No. ChatGPT Plus subscription ($20/month) and API usage billing are completely independent systems — Plus credits only work on chat.openai.com and cannot be consumed via an API Key. Conversely, API usage doesn't count toward your Plus subscription.

Can one API Key be used across Codex CLI and other tools?

Yes. The same API Key can be used for Codex CLI, ChatGPT custom endpoints, IDE plugins, and more. TeamoRouter's unified API Key supports Codex, Claude Code, and Gemini CLI simultaneously — just configure the baseUrl per each tool's documentation.

Is there a risk of API Key leakage?

Yes, if the Key is hard-coded in source code and committed to GitHub. Use environment variables or .env files, and add .env to your .gitignore.

Does TeamoRouter require a credit card to get an API Key?

No. Sign up to get an API Key, prepay before use, and pay with Alipay or other local methods with a low minimum top-up. Outside China you can pay by card.

Codex CLI has both OPENAI_API_KEY and ChatGPT login — which takes priority?

With the TeamoRouter provider configured in config.toml as above, Codex CLI authenticates with the OPENAI_API_KEY named in env_key. The built-in OpenAI provider does not read this variable; it uses the credential saved by codex login (ChatGPT account) or codex login --with-api-key (API Key).

Get Started

1. Sign up for TeamoRouter and get an API Key
2. Follow the Codex install guide to configure env vars and baseUrl
3. Run codex in your terminal and start coding

Get Your Free Codex Setup →

Access Codex, Claude Code, and Gemini CLI stably through TeamoRouter.