Authentication

OpenAI authentication

Codex supports two ways to sign in when using OpenAI models:

• Sign in with ChatGPT for subscription access
• Sign in with an API key for usage-based access

Codex cloud requires signing in with ChatGPT. The Codex CLI and IDE extension support both sign-in methods.

Sign in with ChatGPT

When you sign in with ChatGPT from the Codex CLI or IDE extension, Codex opens a browser window for you to complete the login flow. After you sign in, the browser returns an access token to the CLI or IDE extension.

Sign in with an API key

You can also sign in to the Codex CLI or IDE extension with an API key. Get your API key from the OpenAI dashboard.

OpenAI bills API key usage through your OpenAI Platform account at standard API rates. See the API pricing page.

Secure your Codex cloud account

Codex cloud interacts directly with your codebase, so it needs stronger security than many other ChatGPT features. Enable multi-factor authentication (MFA).

If you use a social login provider (Google, Microsoft, Apple), you aren’t required to enable MFA on your ChatGPT account, but you can set it up with your social login provider.

For setup instructions, see:

• Google
• Microsoft
• Apple

If you access ChatGPT through single sign-on (SSO), your organization’s SSO administrator should enforce MFA for all users.

If you log in using an email and password, you must set up MFA on your account before accessing Codex cloud.

If your account supports more than one login method and one of them is email and password, you must set up MFA before accessing Codex, even if you sign in another way.

Login caching

When you sign in to the Codex CLI or IDE extension using either ChatGPT or an API key, Codex caches your login details and reuses them the next time you start the CLI or extension. The CLI and extension share the same cached login details. If you log out from either one, you’ll need to sign in again the next time you start the CLI or extension.

Codex caches login details locally in a plaintext file at ~/.codex/auth.json or in your OS-specific credential store.

Credential storage

Use cli_auth_credentials_store to control where the Codex CLI stores cached credentials:

# file | keyring | auto
cli_auth_credentials_store = "keyring"

• file stores credentials in auth.json under CODEX_HOME (defaults to ~/.codex).
• keyring stores credentials in your operating system credential store.
• auto uses the OS credential store when available, otherwise falls back to auth.json.

Enforce a login method or workspace

In managed environments, admins may restrict how users are allowed to authenticate:

# Only allow ChatGPT login or only allow API key login.
forced_login_method = "chatgpt" # or "api"

# When using ChatGPT login, restrict users to a specific workspace.
forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"

If the active credentials don’t match the configured restrictions, Codex logs the user out and exits.

These settings are commonly applied via managed configuration rather than per-user setup. See Managed configuration.

Login on headless devices

If you are signing in to ChatGPT with the Codex CLI, there are some situations where the browser-based login UI may not work:

• You’re running the CLI in a remote or headless environment.
• Your local networking configuration blocks the localhost callback Codex uses to return the OAuth token to the CLI after you sign in.

In these situations, prefer device code authentication (experimental, beta). If device code authentication doesn’t work in your environment, use one of the fallback methods.

Preferred: Device code authentication (experimental, beta)

1. Enable device code login in your ChatGPT security settings (personal account) or ChatGPT workspace permissions (workspace admin).
2. In the terminal where you’re running Codex, run codex login --device-auth.
3. Open the link to sign in with your account in your browser, then enter the one-time code.

Fallback: Authenticate locally and copy your auth cache

If you can complete the login flow on a machine with a browser, you can copy your cached credentials to the headless machine.

1. On a machine where you can use the browser-based login flow, run codex login.
2. Confirm the login cache exists at ~/.codex/auth.json.
3. Copy ~/.codex/auth.json to ~/.codex/auth.json on the headless machine.

Treat ~/.codex/auth.json like a password: it contains access tokens. Don’t commit it, paste it into tickets, or share it in chat.

If your OS stores credentials in a credential store instead of ~/.codex/auth.json, this method may not apply. See Credential storage for how to configure file-based storage.

Copy to a remote machine over SSH:

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

Or use a one-liner that avoids scp:

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

Copy into a Docker container:

# Replace MY_CONTAINER with the name or ID of your container.
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"

Fallback: Forward the localhost callback over SSH

If you can forward ports between your local machine and the remote host, you can use the standard browser-based flow by tunneling Codex’s local callback server (default localhost:1455).

1. From your local machine, start port forwarding:

ssh -L 1455:localhost:1455 user@remote

2. In that SSH session, run codex login and follow the printed address on your local machine.

Alternative model providers

When you define a custom model provider in your configuration file, you can choose one of these authentication methods:

• OpenAI authentication: Set requires_openai_auth = true to use OpenAI authentication. You can then sign in with ChatGPT or an API key. This is useful when you access OpenAI models through an LLM proxy server. When requires_openai_auth = true, Codex ignores env_key.
• Environment variable authentication: Set env_key = "<ENV_VARIABLE_NAME>" to use a provider-specific API key from the local environment variable named <ENV_VARIABLE_NAME>.
• No authentication: If you don’t set requires_openai_auth (or set it to false) and you don’t set env_key, Codex assumes the provider doesn’t require authentication. This is useful for local models.