dev/docs/authentication.md

Authentication

Usage-based billing alternative: Use an OpenAI API key

If you prefer to pay-as-you-go, you can still authenticate with your OpenAI API key by setting it as an environment variable:

export OPENAI_API_KEY="your-api-key-here"

This key must, at minimum, have write access to the Responses API.

Migrating to ChatGPT login from API key

If you've used the Codex CLI before with usage-based billing via an API key and want to switch to using your ChatGPT plan, follow these steps:

1. Update the CLI and ensure codex --version is 0.20.0 or later
2. Delete ~/.codex/auth.json (on Windows: C:\\Users\\USERNAME\\.codex\\auth.json)
3. Run codex login again

Forcing a specific auth method (advanced)

You can explicitly choose which authentication Codex should prefer when both are available.

• To always use your API key (even when ChatGPT auth exists), set:

# ~/.codex/config.toml
preferred_auth_method = "apikey"

Or override ad-hoc via CLI:

codex --config preferred_auth_method="apikey"

• To prefer ChatGPT auth (default), set:

# ~/.codex/config.toml
preferred_auth_method = "chatgpt"

Notes:

• When preferred_auth_method = "apikey" and an API key is available, the login screen is skipped.
• When preferred_auth_method = "chatgpt" (default), Codex prefers ChatGPT auth if present; if only an API key is present, it will use the API key. Certain account types may also require API-key mode.
• To check which auth method is being used during a session, use the /status command in the TUI.

Project .env safety (OPENAI_API_KEY)

By default, Codex will no longer read OPENAI_API_KEY or AZURE_OPENAI_API_KEY from a project’s local .env file.

Why: many repos include an API key in .env for unrelated tooling, which could cause Codex to silently use the API key instead of your ChatGPT plan in that folder.

What still works:

• ~/.code/.env (or ~/.codex/.env) is loaded first and may contain your OPENAI_API_KEY for global use.
• A shell-exported OPENAI_API_KEY is honored.

Project .env provider keys are always ignored — there is no opt‑in.

UI clarity:

• When Codex is using an API key, the chat footer shows a bold “Auth: API key” badge so it’s obvious which mode you’re in.

Connecting on a "Headless" Machine

Today, the login process entails running a server on localhost:1455. If you are on a "headless" server, such as a Docker container or are ssh'd into a remote machine, loading localhost:1455 in the browser on your local machine will not automatically connect to the webserver running on the headless machine, so you must use one of the following workarounds:

Authenticate locally and copy your credentials to the "headless" machine

The easiest solution is likely to run through the codex login process on your local machine such that localhost:1455 is accessible in your web browser. When you complete the authentication process, an auth.json file should be available at $CODEX_HOME/auth.json (on Mac/Linux, $CODEX_HOME defaults to ~/.codex whereas on Windows, it defaults to %USERPROFILE%\\.codex).

Because the auth.json file is not tied to a specific host, once you complete the authentication flow locally, you can copy the $CODEX_HOME/auth.json file to the headless machine and then codex should "just work" on that machine. Note to copy a file to a Docker container, you can do:

# substitute MY_CONTAINER with the name or id of your Docker container:
CONTAINER_HOME=$(docker exec MY_CONTAINER printenv HOME)
docker exec MY_CONTAINER mkdir -p "$CONTAINER_HOME/.codex"
docker cp auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json"

whereas if you are ssh'd into a remote machine, you likely want to use scp:

ssh user@remote 'mkdir -p ~/.codex'
scp ~/.codex/auth.json user@remote:~/.codex/auth.json

or try this one-liner:

ssh user@remote 'mkdir -p ~/.codex && cat > ~/.codex/auth.json' < ~/.codex/auth.json

Connecting through VPS or remote

If you run Codex on a remote machine (VPS/server) without a local browser, the login helper starts a server on localhost:1455 on the remote host. To complete login in your local browser, forward that port to your machine before starting the login flow:

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

Then, in that SSH session, run codex and select "Sign in with ChatGPT". When prompted, open the printed URL (it will be http://localhost:1455/...) in your local browser. The traffic will be tunneled to the remote server.