auth.md Codex Docs, 2026-02-19 20:37 UTC → 2026-05-18 22:01 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.

17 22 

23If your environment already provides a ChatGPT access token, the CLI can read

24it from stdin:

25 

26```shell

27printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

28```

29 

18### Sign in with an API key30### Sign in with an API key

19 31 

20You can also sign in to the Codex app, CLI, or IDE Extension with an API key. Get your API key from the [OpenAI dashboard](https://platform.openai.com/api-keys).32You can also sign in to the Codex app, CLI, or IDE Extension with an API key. Get your API key from the [OpenAI dashboard](https://platform.openai.com/api-keys).

21 33 

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

23 35 

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

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

38Codex uses standard API pricing instead.

39 

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

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

42 

43### Use Codex access tokens for enterprise automation

44 

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

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

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

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

49 

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

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

52 

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

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

55 

24## Secure your Codex cloud account56## Secure your Codex cloud account

25 57 

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

45 77 

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

47 79 

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

81 

48## Credential storage82## Credential storage

49 83 

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

76 110 

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

78 112 

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

114 

115## Login diagnostics

116 

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

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

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

120 

121## Custom CA bundles

122 

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

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

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

126custom CA settings apply to login, normal HTTPS requests, and secure WebSocket

127connections.

128 

129```shell

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

131codex login

132```

80 133 

81## Login on headless devices134## Login on headless devices

82 135 

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

133```186```

134 187 

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

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

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

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

192default for automation.

193 

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

136 195 

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