Codex API key: auth.json, login and where the key is stored

Sign in with printenv OPENAI_API_KEY | codex login --with-api-key. Codex saves the key, and by default it saves it in plain text in ~/.codex/auth.json. To keep it in the macOS Keychain instead, set cli_auth_credentials_store = "keyring" in ~/.codex/config.toml and sign in again. For one-off scripted runs, CODEX_API_KEY passes a key without saving it.

We make fidelius, a Mac app built on iCloud Keychain, with no vault or sync of its own, that keeps API keys out of shell and project files. It comes up at the end; everything before that works without it.

Signing in with an API key

The Codex CLI signs in either with your ChatGPT account (codex login, which opens a browser) or with an OpenAI API key. For a key, the authentication docs pipe it in through stdin, so it isn't typed as an argument that would land in your shell history:

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

Exporting OPENAI_API_KEY on its own isn't how current Codex signs in: the login command reads it once and stores it. The old --api-key flag has been retired. codex logout removes the saved credentials.

An API key bills per token to your OpenAI Platform account. A ChatGPT sign-in uses your plan instead. If you need to pin one, forced_login_method = "api" or "chatgpt" in config.toml restricts Codex to that method.

What's in ~/.codex/auth.json

The file holds whichever credential you signed in with: the API key, or the access and refresh tokens from a ChatGPT sign-in. It's plain JSON with file mode 0600, so only your user account can read it. OpenAI's docs are direct about it: treat auth.json like a password, and don't commit it, paste it into tickets or share it in chat.

The file sits in ~/.codex, or in $CODEX_HOME if you set that. Watch for it in dotfiles repos, backups of your home folder and container images built from it.

Moving the key into the macOS Keychain

cli_auth_credentials_store in ~/.codex/config.toml decides where Codex keeps credentials:

ValueWhere the credential goes
fileauth.json in ~/.codex
keyringThe macOS Keychain, and sign-in fails if it isn't available
autoThe Keychain when available, otherwise auth.json
ephemeralMemory only, for the current process

Add the setting near the top of ~/.codex/config.toml, above any [section] header. In TOML, a line below a header belongs to that section, so appending it to the end of the file can put it in the wrong place:

cli_auth_credentials_store = "keyring"

Then sign out, sign in again, and check that the old file is gone:

$ codex logout$ printenv OPENAI_API_KEY | codex login --with-api-key$ ls -l ~/.codex/auth.json

With the Keychain setting in effect, Codex tries to remove auth.json itself. If the file is still there, first check that the setting sits above every [section] header, since a line under a header is ignored for this. If it does and codex login status shows you signed in, delete the leftover file: the key in it still works.

The commands Codex runs get your keys by default

Codex passes your environment on to the commands it runs. Its config reference lists shell_environment_policy.ignore_default_excludes as true by default, which keeps variables whose names contain KEY, SECRET or TOKEN instead of filtering them out. Every API key exported in your shell reaches those commands, and one env prints them into the session. To filter them out, add this section to ~/.codex/config.toml (or add the line to the section if you already have one):

[shell_environment_policy]
ignore_default_excludes = false

Commands that need a key then have to get it some other way, and that's the idea: a key should go only to the command that uses it.

Scripted runs: CODEX_API_KEY

For codex exec, reviews and the SDK, Codex reads a key from CODEX_API_KEY without saving it. The environment variable reference suggests setting it inline when the run touches code from a repository, so the rest of the job doesn't get it. Codex itself still passes it on to the commands it runs, your tests included, unless you set ignore_default_excludes = false as above.

To keep the key in the Keychain, store it once with the macOS security command. With -w last it prompts for the value, so the key doesn't land in your shell history:

$ security add-generic-password -a "$USER" -s openai-api-key -w

Then read it for each run:

$ CODEX_API_KEY="$(security find-generic-password -s openai-api-key -w)" codex exec "run the tests"

Where fidelius fits

fidelius keeps your project API keys in the Keychain, grouped by project, so none of them has to sit in ~/.zshrc or a .env file, and Codex starts without them. With one click it adds instructions telling Codex to run commands that need a key through accio, as in accio myapp npm test, so the key reaches that command and Codex works with the key name, as long as it follows those instructions. When accio sees Codex, it also masks key values in command output, which catches accidents.