Authentication

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 You’ll Walk Away With

• A clear understanding of the two authentication methods and when to use each
• Codex authenticated across all surfaces (App, CLI, IDE extension) with a single sign-in
• 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

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

Billing: Usage is included in your ChatGPT plan (Plus at $20/mo, Pro at $200/mo, Business, Edu, Enterprise). No per-token charges.

Features: Full access to all surfaces including Codex Cloud, cloud threads, GitHub integration with @codex mentions, and automatic code review.

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

# CLI: Start and choose ChatGPT login
codex

# Or explicitly
codex login

API Key

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: Full access to App, CLI, and IDE extension. Some features like Codex Cloud and cloud threads may not be available.

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

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

Caution

Codex Cloud requires ChatGPT login. If you sign in with an API key, you can use the App, CLI, and IDE extension locally, but you cannot launch cloud threads, use @codex in GitHub, or set up automatic code reviews.

Sign In Across All Surfaces

The beautiful thing about Codex authentication: sign in once, and all surfaces pick up your credentials automatically. The App, CLI, and IDE extension share ~/.codex/auth.json (or your OS credential store).

1. Sign in through any surface — the App, CLI, or IDE extension.

2. Open a different surface. It should detect your existing credentials and skip the sign-in flow.

3. If a second surface still prompts you to sign in, check that both surfaces are using the same CODEX_HOME directory (defaults to ~/.codex).

Tip

Prompt to verify authentication is working:

Run this in the CLI after signing in:

codex "What model am I using?"

If Codex responds with the model name (typically GPT-5.3-Codex), authentication is confirmed.

Credential Storage Options

By default, Codex caches credentials in a plaintext file at ~/.codex/auth.json. For better security, you can switch to your operating system’s keyring.

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	Default. Works everywhere. 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.

Caution

If you use file-based storage, never commit ~/.codex/auth.json to version control, paste it into tickets, or share it in chat. It contains access tokens.

Headless and Remote Authentication

Running Codex on a remote server, inside a Docker container, or over SSH? The browser-based login flow will not work. You have three options.

Device Code (Recommended)

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).

Copy Auth Cache

Sign in on a machine with a browser, then copy the credentials to the remote machine.

# 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"

SSH Port Forwarding

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:

• Google MFA setup
• Microsoft MFA setup
• Apple MFA setup

Tip

Prompt to verify cloud access is working:

Go to chatgpt.com/codex and try launching a simple task. If it runs, your MFA and cloud authentication are properly configured.

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 This 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.

Tip

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.

What’s Next

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