auth.md Codex Docs, 2026-02-23 18:27 UTC → 2026-05-14 21:00 UTC

9 9 

10Codex 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.

11 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 

12### Sign in with ChatGPT19### Sign in with ChatGPT

13 20 

14When 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.

19 26 

20OpenAI 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/).

21 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 

33We recommend API key authentication for programmatic Codex CLI workflows, such

34as CI/CD jobs. Don't expose Codex execution in untrusted or public environments.

35 

36### Use Codex access tokens for enterprise automation

37 

38In ChatGPT Enterprise workspaces, admins can allow permitted members to create

39Codex access tokens for trusted, non-interactive Codex local workflows. Use an

40access token when automation needs ChatGPT workspace access, ChatGPT-managed

41Codex entitlements, or enterprise workspace controls without a browser sign-in.

42 

43Access tokens are intended for trusted scripts, schedulers, and private CI

44runners. For general OpenAI API calls, continue to use Platform API keys.

45 

46For setup steps, permissions, rotation, and revocation guidance, see

47[Access tokens](https://developers.openai.com/codex/enterprise/access-tokens).

48 

22## Secure your Codex cloud account49## Secure your Codex cloud account

23 50 

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

43 70 

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

45 72 

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

74 

46## Credential storage75## Credential storage

47 76 

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

74 103 

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

76 105 

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

107 

108## Login diagnostics

109 

110Direct `codex login` runs write a dedicated `codex-login.log` file under

111your configured log directory. Use it when you need to debug browser-login or

112device-code failures, or when support asks for login-specific logs.

113 

114## Custom CA bundles

115 

116If your network uses a corporate TLS proxy or private root CA, set

117`CODEX_CA_CERTIFICATE` to a PEM bundle before logging in. When

118`CODEX_CA_CERTIFICATE` is unset, Codex falls back to `SSL_CERT_FILE`. The same

119custom CA settings apply to login, normal HTTPS requests, and secure websocket

120connections.

121 

122```shell

123export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem

124codex login

125```

78 126 

79## Login on headless devices127## Login on headless devices

80 128 

130docker cp ~/.codex/auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json"178docker cp ~/.codex/auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json"

131```179```

132 180 

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

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

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

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

185default for automation.

186 

133### Fallback: Forward the localhost callback over SSH187### Fallback: Forward the localhost callback over SSH

134 188 

135If 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`).189If 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`).