Authentication

Codex authentication offers two mutually exclusive methods: signing in with a ChatGPT subscription, which unlocks local and cloud capabilities including Codex Cloud, or providing an OpenAI API key, which bills per token and works for local surfaces but limits ChatGPT workspace and cloud features. The choice determines billing, available features, and whether cloud threads function, though it does not change how Codex behaves once authenticated.

You installed Codex, launched it, and hit the sign-in screen. Two options stare back at you: “Sign in with ChatGPT” and “Sign in with API Key.” Picking the wrong one does not break anything, but it determines how you are billed, which features you can access, and whether cloud threads work at all.

What Setting Up Authentication Gets You

A clear understanding of the two authentication methods and when to use each
Local credential reuse across CLI and the OpenAI IDE extension, with desktop and cloud boundaries understood
Credential storage configured for your security preferences
Headless/remote authentication working for SSH and Docker environments
Multi-factor authentication set up for Codex Cloud access

Two Ways to Authenticate

Codex supports two authentication methods. They are mutually exclusive per session — you pick one when you sign in.

ChatGPT Subscription
API Key

How it works: Codex opens a browser window, you sign in with your ChatGPT account, and the browser returns an access token.

Billing: Your plan includes an account-specific Codex allowance. Eligible plans can buy additional ChatGPT credits after included usage; limits, model access, and credit options vary by plan and workspace.

Features: Local and cloud capabilities allowed by your plan, workspace role, and admin policy. ChatGPT authentication is required for Codex Cloud and ChatGPT-managed integrations, but authentication alone does not grant every feature.

Best for: Individual developers and teams already on ChatGPT plans.

# CLI: Start and choose ChatGPT login
codex

# Or explicitly
codex login

How it works: You provide an OpenAI API key from platform.openai.com/api-keys. Codex stores it locally and sends it with each request.

Billing: Usage-based at standard API rates. You pay per token, billed to your OpenAI Platform account.

Features: Local work in the ChatGPT desktop app, CLI, and OpenAI IDE extension. ChatGPT workspace and cloud features are limited or unavailable.

Best for: Developers who want usage-based billing, already have API credits, or need to separate Codex costs from their ChatGPT subscription.

# CLI: Start and choose API key login
codex

# Non-interactive (headless/CI): pipe the key from your environment
printenv OPENAI_API_KEY | codex login --with-api-key

# The App and IDE extension also offer API key login in their sign-in screens

Local OpenAI clients can reuse cached credentials when they point at the same CODEX_HOME. The CLI and OpenAI IDE extension explicitly share the same cache; desktop behavior depends on the selected local account and credential store. Cloud/browser sessions remain separate.

Sign in through the CLI or OpenAI IDE extension.
Open the other local client. It should detect credentials from the same CODEX_HOME.
Sign into ChatGPT desktop or cloud separately if prompted; those surfaces can have their own account/session state.

Prompt to verify authentication is working:

Run this in the CLI after signing in:

codex login status

An exit code of 0 confirms authentication. Model entitlement is a separate check: Codex exposes Terra to Free and Go, and Sol, Terra, and Luna to eligible Plus, Pro, Business, and Enterprise users; workspace policy can narrow that list.

Credential Storage Options

Codex can cache credentials in ~/.codex/auth.json or in your operating system’s keyring, depending on cli_auth_credentials_store and platform support.

Configure the storage method in ~/.codex/config.toml:

# Options: "file" | "keyring" | "auto"
cli_auth_credentials_store = "keyring"

Method	Where credentials live	When to use
`file`	`~/.codex/auth.json`	Portable fallback. Treat the file like a password.
`keyring`	macOS Keychain, Linux Secret Service, Windows Credential Manager	Better security. Requires a GUI session or unlocked keyring.
`auto`	Keyring if available, falls back to file	Best of both worlds for most developers.

Headless and Remote Authentication

Running Codex on a remote server, inside a Docker container, or over SSH? If the normal localhost browser callback is unavailable, use one of these options.

Device code authentication lets you sign in without a local browser.

# Start device code login
codex login --device-auth

Codex prints a URL and a one-time code. Open the URL on any device with a browser, sign in, enter the code, and Codex completes authentication.

Prerequisites: Enable device code login in your ChatGPT security settings (personal account) or workspace permissions (admin).

# From your local machine to a remote server
ssh user@remote 'mkdir -p ~/.codex'
scp ~/.codex/auth.json user@remote:~/.codex/auth.json

For Docker containers:

CONTAINER_HOME=$(docker exec MY_CONTAINER printenv HOME)
docker exec MY_CONTAINER mkdir -p "$CONTAINER_HOME/.codex"
docker cp ~/.codex/auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json"

Tunnel the Codex callback server through SSH:

# From your local machine
ssh -L 1455:localhost:1455 user@remote

# In that SSH session, on the remote machine
codex login

Follow the login URL on your local browser. The OAuth callback routes through the tunnel back to the remote Codex process.

Multi-Factor Authentication for Codex Cloud

Codex Cloud interacts directly with your codebase through GitHub, so OpenAI requires stronger security. If you log in with email and password, you must enable MFA before accessing Codex Cloud.

If you use a social login provider (Google, Microsoft, Apple), MFA is not strictly required on your ChatGPT account, but you should still enable it with your provider:

Enterprise Authentication

For managed environments, admins can restrict authentication methods:

# ~/.codex/config.toml or managed config

# Force all users to sign in with ChatGPT (no API keys)
forced_login_method = "chatgpt"

# Restrict to a specific workspace
forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"

If the active credentials do not match the configured restrictions, Codex logs the user out and exits.

When Codex Authentication Breaks

Browser does not open during sign-in: Check that your default browser is configured. On macOS, verify in System Settings > Default Web Browser. On Linux, check xdg-settings get default-web-browser.

Sign-in succeeds but Codex says “not authenticated”: The auth cache may be stale. Delete ~/.codex/auth.json and sign in again. If using keyring storage, check that the keyring is unlocked.

API key works in CLI but not in the App: Make sure you entered the key in the App’s own sign-in flow. The App does not read the OPENAI_API_KEY environment variable automatically.

“MFA required” error when accessing Cloud: Enable multi-factor authentication on your ChatGPT account or social login provider. Email/password accounts must have MFA enabled directly.

Credentials not shared between surfaces: Ensure CODEX_HOME is the same for all surfaces. If you set a custom CODEX_HOME in one terminal but not in the App, they will use different auth caches.

Prompt to debug authentication issues:

codex "Check my authentication status and tell me which login method I'm using"

Codex will report whether you are signed in via ChatGPT or API key and which features are available.

Where to Go Next After Authentication

Configure Codex Set your default model, approval mode, sandbox level, and feature flags