codex login --device-auth is the cleanest way to authenticate the Codex CLI on a headless server: no browser on the box, no copy-pasting an API key, just a one-time code on a phone or laptop. But the first run often fails with no obvious error — the prompt appears, you complete it, and nothing logs in. The missing piece is almost always a single toggle in your ChatGPT account.
This is the exact fix, the managed-workspace exception, and the verification flow that confirms it worked.
Why the Login Stalls
Device code authorization is an OAuth flow. The CLI shows a link and a short code; you authorize the session from a separate device that already has a browser and a signed-in ChatGPT account. Codex itself does not require the toggle to start the flow — the prompt will happily print the code. What it requires is for your account to be allowed to redeem that code.
If device code authorization is disabled at the account or workspace level, the code is rejected server-side and the CLI never receives a token. You see the prompt, you enter the code, and the session silently fails.
The fix is not on the server. It is in ChatGPT’s Security Settings.
Enable Device Code Authorization
Open ChatGPT and navigate:
Profile → Settings → Security → Device code authorization
Flip the toggle on. That is the entire account-level change.
For a managed workspace (ChatGPT Team, Enterprise, or Edu), the toggle may be greyed out or absent entirely. In that case an administrator must enable device-code login in the workspace permissions before any member can use it. Ask your workspace admin — individual members cannot override this at the account level.
Once the toggle is on (or the workspace permission is granted), re-run the login from the same machine.
Run the Login Again
codex login --device-authA successful run looks like this:
Welcome to Codex [v0.145.0]
OpenAI's command-line coding agent
Follow these steps to sign in with ChatGPT using device code authorization:
1. Open this link in your browser and sign in to your account
https://auth.openai.com/codex/device
2. Enter this one-time code (expires in 15 minutes)
AAAAB-BB6TU
Continue only if you started this login in Codex. If a website or another person gave you this code, cancel.
Successfully logged inOpen the link on any device where you are signed in to ChatGPT, paste the one-time code, and authorize. The code expires in 15 minutes, so do it in one sitting. The CLI prints Successfully logged in the moment the code is redeemed.
Security Notes
Device code authorization is designed for exactly this situation — a machine with no browser — so the secret (the short code) is low-value on its own. Treat it like a one-time PIN:
- Only enter a code you initiated yourself. The CLI prints a warning for exactly this reason: if a website or another person gave you the code, cancel.
- The code is single-use and short-lived. Once redeemed it cannot be reused, and a failed or timed-out code simply expires.
- On managed workspaces, the admin-controlled permission is the real gate. If you cannot enable it, that is working as intended — it keeps workspace auth policy centralized.
Verify the Session
After Successfully logged in, the credentials are stored locally on that instance. You do not need to keep the code or re-run anything. To confirm the agent is usable, start a session or run a harmless command:
codex "list the files in the current directory"If Codex responds, the device-code session is live. The redeemed code is no longer needed — it has already been consumed.
What I Learned
The trap with Codex device-code auth is that the failure is silent and the cause is far away from the terminal. The CLI does its part; the blocker is a security setting in your ChatGPT account, or a workspace permission your admin owns. Flip the toggle, re-run codex login --device-auth, enter the code on a signed-in device, and the session comes up cleanly — no API key juggling on a headless box.
