Codex "refresh token was already used": the cause and the fix
Codex's "refresh token was already used" error and its four siblings: what each means, why a copied auth.json fails, and how to sign in a server or job.
“Your refresh token was already used” means another copy of the same Codex sign-in refreshed it first. Codex replaces the refresh token each time it uses it, so when one ~/.codex/auth.json lives on two machines, such as a laptop and the server it was copied to, whichever refreshes second is holding a dead token. Run codex logout, then codex login --device-auth on that machine, so it has a sign-in of its own, and stop using the copied file anywhere else. For scheduled or parallel jobs, use an API key instead of a shared ChatGPT sign-in.
The five messages
Codex has five versions of this message, and each comes from a different reason the refresh failed. They are defined in Codex’s login code:
- “Your access token could not be refreshed because your refresh token was already used. Please log out and sign in again.” OpenAI saw that refresh token used once already. Two holders of one sign-in: two machines, two jobs, or another program reading the same file.
- “Your access token could not be refreshed because your refresh token has expired. Please log out and sign in again.” The refresh token ran out of time before this machine used it.
- “Your access token could not be refreshed because your refresh token was revoked. Please log out and sign in again.” OpenAI ended that sign-in on its side.
- “Your access token could not be refreshed. Please log out and sign in again.” Any other permanent refusal, including a plain
invalid_grantor a 401 from the token service. - “Your access token could not be refreshed because you have since logged out or signed in to another account. Please sign in again.” This Codex process started under one account, and the stored sign-in now belongs to a different account, or to none.
The fix is the same for all five: sign this machine in again. What differs is whether it happens again, which depends on why two holders of one sign-in existed in the first place.
A sign-in copied to a server
The usual way to get here is copying ~/.codex/auth.json from a laptop to a server, because a server has no browser for the normal sign-in. That works until both machines refresh. Codex refreshes a sign-in once its last refresh is “older than about 8 days”, and writes the new tokens back to its own copy of the file. The other machine still holds the old refresh token, and the next time it refreshes, OpenAI turns it away. A reporter on Codex’s tracker with “single OpenAI account, three machines” describes the result: the laptop signed in most recently works, and the two servers both fail.
OpenAI’s page on Codex in CI states the rule: “Do not share the same file across concurrent jobs or multiple machines.” So there are two clean ways to set up a server:
- Sign the server in with its own device code:
codex login --device-authprints a link and a code you approve from your phone or laptop. Each machine then holds its own sign-in, and they never collide. If that command is refused, the setting that turns device-code sign-in on is in ChatGPT’s security settings. - Copy the file, and treat the server as the only machine that uses it from then on. Sign the laptop in again separately if you still want Codex there.
The guide to Codex on a Linux server covers the device-code sign-in and the rest of the setup step by step.
Jobs running at the same time
On one machine, Codex’s login code re-reads the stored sign-in before it refreshes, and if another process has already written a new token there, it uses that instead of refreshing again, which is meant to keep processes sharing one file on one machine from colliding. What collides is jobs that each hold their own copy of the same sign-in: CI runners that restore auth.json from one secret, containers each started from the same file, or two refreshes landing at the same moment. OpenAI’s CI page lists “another machine or concurrent job rotated the token first” among the reasons a runner can no longer refresh, and its advice is “Use one auth.json per runner or per serialized workflow stream.”
Another program reading Codex’s file counts as a second holder too. Hermes Agent, for instance, can borrow Codex’s sign-in when it has none of its own, and then the two refresh the same token.
After switching accounts
The last of the five messages follows a codex logout or a sign-in to a different account while another Codex is still running. Codex keeps one stored sign-in per Codex home, normally ~/.codex. A maintainer explains on the tracker: “The auth mechanism in Codex is not designed to support usage of multiple concurrent instances of Codex on the same system with different logins.” Signing in to the second account replaces the stored tokens, and the processes started under the first account cannot refresh.
Close every Codex session from before the switch and start them again. That includes ones in tmux sessions you have forgotten, and background codex app-server processes: reports in the same thread cleared the error only after stopping a stale app-server. On Codex older than 0.117.0, update first; a maintainer said of an earlier refresh bug, “We think this is fixed in the latest release (0.117.0).” Reports of the message continue on later releases, from the causes above.
Use an API key for jobs
A ChatGPT sign-in belongs to one holder at a time, and a refresh token can expire or be revoked while a job sits waiting. An API key does not refresh, so it has none of these failures. OpenAI’s CI page says “The right way to authenticate automation is with an API key,” and for codex exec the key can be given for a single run:
CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"CopiedTo save a key as the machine’s sign-in instead, pipe it to codex login --with-api-key:
printenv OPENAI_API_KEY | codex login --with-api-keyCopiedThe difference is the bill. Usage on a key is billed through your OpenAI Platform account “at standard API rates”, not drawn from your ChatGPT plan, and Codex cloud needs a ChatGPT sign-in. What a plan includes is in which ChatGPT plans include Codex, and running Codex and Claude Code on a schedule covers the rest of an unattended job’s setup. A key saved this way sits in ~/.codex/auth.json in plain text, unless Codex is set to use the system’s credential store, so give the job a key of its own that you can revoke on its own.