Signing in to Codex CLI with a ChatGPT account or an API key

Who this is for and what you will be able to do

This guide is for developers who want to use Codex from the terminal. After reading it you should be able to choose between signing in with a ChatGPT account and signing in with an API key, run the login and logout commands, find where credentials are stored, and pick a fallback when the browser login does not work on a remote machine.^[1][2]

What the Codex CLI is

The official quickstart points developers who want Codex in a terminal or a code editor to two options: the Codex CLI and the Codex IDE extension.^[1]

This guide covers sign-in only. Installation steps are not included, so it assumes the CLI is already installed.

Two ways to sign in

When Codex uses OpenAI models, you can sign in with ChatGPT for subscription access, or sign in with an API key for usage-based access.^[2] The desktop app, the CLI, and the IDE extension support both methods for local work. Codex cloud requires signing in with ChatGPT.^[2]

The two methods are billed differently. With an API key, Codex uses standard API pricing instead of the credits included in a ChatGPT plan. OpenAI bills API key usage through the OpenAI Platform account.^[2]

An API key also covers a narrower set of features. Features that depend on ChatGPT workspace access or cloud services may be limited or unavailable.^[2] Check that a feature works under your sign-in method before you depend on it.

The docs describe API key authentication as suitable for programmatic CLI workflows such as CI/CD jobs, and they call it the recommended default for automation. They also advise against running Codex execution in untrusted or public environments.^[2]

Sign in with a ChatGPT account

1. Run codex login. The CLI opens a browser flow, which is the default path when no valid session exists.^[2]
2. Run codex login status to see which authentication method is active.^[2]

Sign in with an API key

Get an API key from the OpenAI dashboard.^[2] Then pipe the key from your environment variable to codex login through standard input:

printenv OPENAI_API_KEY | codex login --with-api-key

Log out

Run codex logout to clear the current stored credentials.^[2] After you log out, you will need to sign in again the next time you start the CLI or the extension.^[2]

Where credentials are stored

Codex caches login details in one of two places: a plaintext file at ~/.codex/auth.json, or the operating system's credential store.^[2] The CLI and the IDE extension share the same cached login, so logging out of one means the other will also ask you to sign in again.^[2]

The cli_auth_credentials_store setting controls where the CLI keeps the credentials. Its values are file, keyring, auto, and ephemeral.^[2]

# file | keyring | auto | ephemeral
cli_auth_credentials_store = "keyring"

The four values behave as follows:

• file stores credentials in auth.json under CODEX_HOME, which defaults to ~/.codex.
• keyring stores them in the operating system credential store and fails if that store is unavailable.
• auto uses the operating system credential store when it is available and falls back to auth.json otherwise.
• ephemeral keeps credentials in memory for the current process only.^[2]

The auth.json file contains access tokens, so treat it like a password. Do not commit it, paste it into tickets, or share it in chat.^[2]

Sign in on a remote or headless machine

On a remote or headless machine the browser login may not work. In that case the docs recommend device code authentication, which is in beta.^[2]

Device code login must be turned on first. A personal account enables it in ChatGPT security settings; a workspace admin enables it in workspace permissions.^[2] Once it is on, run codex login --device-auth.^[2]

If device code login is not available in your environment, the docs give two fallbacks:

• Run codex login on a machine with a browser, then copy ~/.codex/auth.json to the same path on the headless machine. This may not apply if your credentials are kept in an operating system credential store.^[2]
• Forward Codex's local callback port over SSH. The default callback is localhost:1455. On your local machine run ssh -L 1455:localhost:1455 user@remote, then run codex login in that SSH session and open the address it prints on your local machine.^[2]

Replace user@remote with your own username and host.

Corporate networks and custom CA certificates

If your network uses a corporate TLS proxy or a private root CA, set CODEX_CA_CERTIFICATE to a PEM bundle before you log in. If it is unset, Codex falls back to SSL_CERT_FILE.^[2]

Debugging a failed login

Direct codex login runs write a codex-login.log file under your configured log directory. Look there first when browser login or device code login fails.^[2]

If you configure keyring and the operating system credential store is unavailable, sign-in fails. You can switch to auto or file instead.^[2]

Limits

• With an API key, features that depend on ChatGPT workspace access or cloud services may be limited or unavailable.^[2]
• Codex cloud requires signing in with ChatGPT. If your account uses email and password, you must set up multi-factor authentication (MFA) before you can access Codex cloud.^[2]
• Device code authentication is in beta.^[2]

Next steps

For the full details on sign-in methods and credential storage, read the official authentication page.^[2] The quickstart is the place to start.^[1]