auth.md Codex Docs, 2026-02-19 20:37 UTC → 2026-03-08 00:35 UTC

1# Authentication1# Authentication

2 2 

3Sign-in methods for Codex

4 

5## OpenAI authentication3## OpenAI authentication

6 4 

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

11 9 

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

13 11 

12Your sign-in method also determines which admin controls and data-handling policies apply.

13 

14- With sign in with ChatGPT, Codex usage follows your ChatGPT workspace permissions, RBAC, and ChatGPT Enterprise retention and residency settings

15- With an API key, usage follows your API organization's retention and data-sharing settings instead

16 

17For the CLI, Sign in with ChatGPT is the default authentication path when no valid session is available.

18 

14### Sign in with ChatGPT19### Sign in with ChatGPT

15 20 

16When you sign in with ChatGPT from the Codex app, 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.21When you sign in with ChatGPT from the Codex app, 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.

21 26 

22OpenAI bills API key usage through your OpenAI Platform account at standard API rates. See the [API pricing page](https://openai.com/api/pricing/).27OpenAI bills API key usage through your OpenAI Platform account at standard API rates. See the [API pricing page](https://openai.com/api/pricing/).

23 28 

29Features that rely on ChatGPT credits, such as [fast mode](https://developers.openai.com/codex/speed), are

30available only when you sign in with ChatGPT. If you sign in with an API key,

31Codex uses standard API pricing instead.

32 

33Recommendation is to use API key authentication for programmatic Codex CLI workflows (for example CI/CD jobs). Don't expose Codex execution in untrusted or public environments.

34 

24## Secure your Codex cloud account35## Secure your Codex cloud account

25 36 

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

45 56 

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

47 58 

59For sign in with ChatGPT sessions, Codex refreshes tokens automatically during use before they expire, so active sessions usually continue without requiring another browser login.

60 

48## Credential storage61## Credential storage

49 62 

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

76 89 

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

78 91 

79These settings are commonly applied via managed configuration rather than per-user setup. See [Managed configuration](https://developers.openai.com/codex/security#managed-configuration).92These settings are commonly applied via managed configuration rather than per-user setup. See [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration).

80 93 

81## Login on headless devices94## Login on headless devices

82 95 

132docker cp ~/.codex/auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json"145docker cp ~/.codex/auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json"

133```146```

134 147 

148For a more advanced version of this same pattern on trusted CI/CD runners, see

149[Maintain Codex account auth in CI/CD (advanced)](https://developers.openai.com/codex/auth/ci-cd-auth).

150That guide explains how to let Codex refresh `auth.json` during normal runs and

151then keep the updated file for the next job. API keys are still the recommended

152default for automation.

153 

135### Fallback: Forward the localhost callback over SSH154### Fallback: Forward the localhost callback over SSH

136 155 

137If 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`).156If 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`).