claude setup-token: the one-year Claude Code token

claude setup-token opens the same browser sign-in as /login, then prints a one-year OAuth token for your Claude plan and saves it nowhere. You set it as CLAUDE_CODE_OAUTH_TOKEN on the machine, script or CI job that has no browser. It needs Pro, Max, Team or Enterprise, and it can only make model requests: no Remote Control, no claude.ai connectors.

What we say about Claude Code's behaviour comes from Anthropic's Claude Code docs, which we read on 24 October 2026: the authentication page, the CLI and environment variable references, and the error and Remote Control troubleshooting pages.

What claude setup-token does#

Run it in a terminal on a computer with a browser:

claude setup-token

The browser opens on the same approval page /login uses. Approve it with the account whose plan the work should run on, and the token prints in the terminal. Copy it then, because Claude Code doesn't store it: the CLI reference says it "prints the token to the terminal without saving it".

Then set it wherever Claude Code should run on it:

# macOS, Linux, WSL
export CLAUDE_CODE_OAUTH_TOKEN=your-token

# Windows PowerShell
$env:CLAUDE_CODE_OAUTH_TOKEN = "your-token"

In Windows CMD it is set CLAUDE_CODE_OAUTH_TOKEN=your-token. Every claude started from that shell, including claude -p in a script, now runs on the plan that approved the token, unless a credential higher in the list below is also set. Claude Code headless mode covers the -p side: output formats, the flags that limit tools and turns, and running it in CI.

The token runs on a subscription, and the docs say it needs Pro, Max, Team or Enterprise, so it's no use on a free Claude account. For that account, or for a product other people use, the route is a Claude Console API key.

Where CLAUDE_CODE_OAUTH_TOKEN sits among Claude Code's credentials#

Claude Code uses one credential per session and picks it from a fixed list. The precedence section of the authentication page ranks them:

Two things follow. A job that exports both an API key and the token bills the API key, because rank 3 beats rank 5; Claude Code using your API key, not your plan shows how to find where a key is set. And the token beats your own /login, so a token left in ~/.zshrc decides which account every new terminal uses.

To check which one won, run /status in a session. When the token is in use, the docs say /status shows an Auth token row reading CLAUDE_CODE_OAUTH_TOKEN.

The /login trap while the variable is set#

If you run /login while CLAUDE_CODE_OAUTH_TOKEN is set, Claude Code moves the current session to the new login. Every new session reads the variable again, until you remove it from your shell profile or from the env block of a settings file. So the login looks fixed, and the next terminal is back on the token. That loop is one of the causes in Claude Code keeps asking you to log in.

What a setup-token token can't do#

Per the authentication page, the token "can only make model requests, so it can't establish Remote Control sessions or fetch claude.ai connectors". MCP servers you configure locally still work.

It also does nothing in bare mode. --bare skips OAuth and the keychain completely, and the docs say it "does not read CLAUDE_CODE_OAUTH_TOKEN". A script that passes --bare has to use ANTHROPIC_API_KEY or an apiKeyHelper instead.

Fix "Remote Control requires a full-scope login token"#

That message means the session is running on a setup-token token. The Remote Control troubleshooting page says to sign in with a full-scope token instead:

1. Remove CLAUDE_CODE_OAUTH_TOKEN from the shell you start Claude Code in, and from any settings file's env block: unset CLAUDE_CODE_OAUTH_TOKEN clears it for the current shell.
2. Run claude auth login and choose your claude.ai account.
3. Start Remote Control again and check /status: the Auth token row should be gone.

Step 1 matters because the variable outranks your login: sign in without removing it and the next session is back on the token. Other Remote Control errors, from the wrong plan to an organisation policy, are in Claude Code Remote Control not working.

When the token expires#

The token lasts one year. When it runs out, or is revoked, requests fail with errors such as OAuth token has expired with a 401, and in -p mode Failed to authenticate. API Error: 401 OAuth token has expired. According to the error reference, Claude Code keeps sending the value you set and doesn't fall back to a stored login. Run claude setup-token again, replace the secret, and restart whatever uses it.

Write the day you made it next to the secret, so you know when the year is up. Anthropic's docs also describe no way to list or revoke these tokens: claude setup-token only creates them, and a request for a revoke command (#57400) was closed as not planned on 26 June 2026. Plan as if a token you paste somewhere stays valid for its whole year.

One token per account for scripts#

If your scripts run on two Claude accounts, make one token per account and keep them apart:

1. Run claude setup-token and approve it in the browser with the first account.
2. Store the token at once, labelled with the account's email and the date.
3. Sign out of claude.ai in that browser and sign in as the second account, so the approval page shows the right one.
4. Run claude setup-token again, approve, and store the second token the same way.

Then choose the account per command, not per shell. On a Mac the Keychain works as a secrets store (security add-generic-password -s claude-token-work -a "$USER" -w prompts for the value):

CLAUDE_CODE_OAUTH_TOKEN="$(security find-generic-password -s claude-token-work -w)" \
  claude -p "Summarise the open TODOs in this repo"

Any password manager with a command line does the same job, and in CI the platform's secret store does. In GitHub Actions the secret is named CLAUDE_CODE_OAUTH_TOKEN and passed as claude_code_oauth_token; Claude Code GitHub Actions setup has the workflow. Never put a token in a repository, a Dockerfile or a committed .env file. The same goes for a dev container or a server you reach over SSH: give the token to the environment, not to the image or the code (Claude Code in a dev container covers keeping it as a Codespaces secret, and Claude Code over SSH covers signing in on a server with no browser).

A token is your login in another form, and the rules for your account still apply. Anthropic's Consumer Terms say "You may not share your Account login information, Anthropic API key, or Account credentials with anyone else". They also rule out automated access "Except when you are accessing our Services via an Anthropic API Key or where we otherwise explicitly permit it"; the Claude Code docs present setup-token for "CI pipelines and scripts", and say no more than that about where the line sits. For a secret shared across a team's repositories, the GitHub Actions page recommends a Console API key, because an OAuth token "is tied to the subscription of the person who ran claude setup-token". And the legal and compliance page says claude.ai OAuth is meant for ordinary use of Claude Code and Anthropic's other native apps, which is why the token isn't for other tools (using your Claude plan in other tools covers that). Use only accounts you own and are entitled to use.

setup-token on a work-managed computer#

Companies can lock Claude Code logins to their own organisation with forceLoginOrgUUID in managed settings. The authentication page lists which login paths check it, and claude setup-token and /install-github-app "enforce only forceLoginMethod, so they can mint a token in a different organization". The same page says Claude Code exits at startup when the claude.ai credential in use belongs to an organisation that isn't listed, but it doesn't say in so many words whether that check covers a token set in CLAUDE_CODE_OAUTH_TOKEN.

If you look after those settings, don't count on the organisation lock to stop people minting tokens for other organisations. If you work on a machine under that policy, whether a personal token belongs on it, or a work token on your own computer, is your employer's call before it is a technical question.

How Shuriken handles Claude sign-ins#

Shuriken doesn't take a pasted token. Each Claude account is a source you add in Settings › Sources › Add source with Sign in, approved in your browser, or with Add current for the login already on that computer. Each Claude source keeps its own sign-in in its own folder, the same idea as one CLAUDE_CONFIG_DIR per account.

The agents Shuriken starts don't inherit the API keys or login tokens your shell exports, CLAUDE_CODE_OAUTH_TOKEN included. So a token you set in ~/.zshrc for scripts can't move a Shuriken chat onto that account, and the /login trap above doesn't apply there. With two or more Claude sources, hot swapping (Shuriken moves your chats to another of your accounts when one nears its limit, 99% by default) keeps a chat going without you changing anything. Add only accounts you own and are entitled to use. To try it with your own plans, download Shuriken.