GuidesHosting choices

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.

November 14, 2026The Everpod team
The short answer

“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:

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:

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"
Copied

To 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-key
Copied

The 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.

Run Codex on an always-on developer pod.

A developer pod is a permanent cloud computer (VPS), set up and secured for you, with your pick of Claude Code, Codex, OpenCode, Pi, Hermes and OpenClaw installed. Run more agents at once than your laptop can hold, and keep them working when it’s closed. From $24 a month, built in about ten minutes.