For a non-interactive Claude Code job in CI, when do you authenticate with claude setup-token and CLAUDE_CODE_OAUTH_TOKEN instead of ANTHROPIC_API_KEY?
answer
- no browser on the runner
- subscription-backed, one-year token
- printed once, never saved
- tied to one person's plan
- --bare ignores it
basics
~20 sUse claude setup-token when CI should run on a Pro, Max, Team or Enterprise subscription: it prints a one-year OAuth token you store as CLAUDE_CODE_OAUTH_TOKEN. Use a Console ANTHROPIC_API_KEY for shared secrets, per-token billing, or --bare runs.
solid answer
~40 sA runner cannot complete a browser login, so it needs a credential in the environment. `claude setup-token` runs the same browser authorization as `/login` on your machine and **prints a one-year OAuth token without saving it**; you store it as a CI secret and expose it as `CLAUDE_CODE_OAUTH_TOKEN`. It authenticates with **your subscription**, so it needs a Pro, Max, Team or Enterprise plan and is tied to the person who generated it - for a secret shared across repositories, a Console `ANTHROPIC_API_KEY` is the better fit. The token can only make model requests: no Remote Control and no claude.ai connectors, though locally configured MCP servers work. It ranks below `ANTHROPIC_API_KEY` and `apiKeyHelper`, so a leftover key on the runner wins, and `--bare` does not read it at all.
code
bash · 7 lines# Once, on your own machine (opens the browser, prints the token):
claude setup-token
# In the CI job, from the secret store:
export CLAUDE_CODE_OAUTH_TOKEN="<token from your CI secret store>"
unset ANTHROPIC_API_KEY # a leftover key would outrank the token
claude -p "Summarise the failing tests in test-report.xml" --allowedTools "Read"go deeper
Know that CI cannot do a browser login, and that claude setup-token prints a token you store as CLAUDE_CODE_OAUTH_TOKEN.
Explain who the token bills, its one-year life, that it is never saved, and what it cannot do compared with a /login session.
Spot the runner traps: a higher-ranked key that wins under -p, and --bare ignoring the token; choose a Console key for shared secrets.
Decide whether automation runs on personal subscription tokens or organization keys, weighing ownership, offboarding risk and billing visibility.
## The problem CI has A CI runner or a script has no person at a browser, so the normal `/login` flow cannot finish there. Claude Code therefore reads credentials from the environment, and there are two common choices for a job that calls the Anthropic API directly: a **subscription token** or a **Console API key**. A cloud provider switch is a third, covered with the provider setup. ## Generating the subscription token 1. On your own machine, run `claude setup-token`. 2. It opens the **same browser authorization flow as `/login`**. 3. After you approve, it **prints** a long-lived OAuth token, valid for **one year**, to the terminal. It does **not** save the token anywhere. 4. Copy it into your CI system's secret store and expose it to the job as `CLAUDE_CODE_OAUTH_TOKEN`. When the token expires, you generate a new one and restart whatever uses it; Claude Code uses the token you set for the whole session. ## Token or key: how to choose | Question | `CLAUDE_CODE_OAUTH_TOKEN` (from `claude setup-token`) | `ANTHROPIC_API_KEY` (Console) | |---|---|---| | What it authenticates as | your Pro, Max, Team or Enterprise subscription | a Claude Console organization | | Who it belongs to | the person who ran `setup-token` | the organization that issued the key | | Billing | draws on that subscription | per token, to the Console organization | | Works with `--bare` | **no** | yes | | Shared across many repositories | poor fit | the documented choice | The docs say it plainly for repository automation: for a secret shared across repositories, use a Console API key, because an OAuth token is tied to the subscription of whoever generated it. If that person leaves or changes plan, every job using their token is affected. ## What the token cannot do - It **can only make model requests**. It cannot establish **Remote Control** sessions and cannot fetch **claude.ai connectors**. - MCP servers you configure locally still work, because they do not depend on a claude.ai login. If a job needs a remote tool, configure that server in the job's own settings rather than relying on a connector from your claude.ai account. - It is still a personal credential. Anyone holding the secret can spend from the generating person's plan until it expires, so scope who can read it as you would any production secret. ## Precedence traps on a runner `CLAUDE_CODE_OAUTH_TOKEN` is fifth in Claude Code's credential order. Anything above it that happens to be present wins: - a cloud-provider switch such as `CLAUDE_CODE_USE_BEDROCK`; - `ANTHROPIC_AUTH_TOKEN`; - `ANTHROPIC_API_KEY` - and under `claude -p` a present key is always used, with no approval prompt; - an `apiKeyHelper` script from a settings file. So a runner image that already exports an `ANTHROPIC_API_KEY` silently bills that key's organization even though you configured the subscription token. The other trap is **bare mode**. `claude --bare -p` skips most auto-discovery for reproducible scripted runs and **never reads OAuth credentials or the keychain** - including `CLAUDE_CODE_OAUTH_TOKEN`. A bare run needs `ANTHROPIC_API_KEY`, an `apiKeyHelper` passed through `--settings`, or a cloud provider's own credentials. What else bare mode skips is the headless-mode material. ## A runner checklist 1. Decide whose account pays: a person's subscription (`CLAUDE_CODE_OAUTH_TOKEN`) or the organization's Console (`ANTHROPIC_API_KEY`). 2. Store the credential in the CI system's secret store, never in the repository or a committed settings file. 3. Make sure nothing above your chosen credential is present in the job's environment or in a settings file the job loads. 4. Note the expiry: a setup-token token lasts a year, so put its renewal in someone's calendar, and plan for what happens if its owner leaves. 5. Remember that deleting a stored secret does not revoke the credential it held; retire a Console key in the Console itself. ## Interactive use of the variable On a developer machine the variable behaves differently from `/login`: if you run `/login` while `CLAUDE_CODE_OAUTH_TOKEN` is set, the **current** session switches to the new login, but every **new** session reads the variable again until you remove it from your shell profile or from the `env` block of a settings file. Treat it as a CI and scripting credential, not a way to log in day to day. For wiring the secret into a workflow file, the GitHub Actions material covers the action's input; the credential decision is the one above.
- Your CI job sets CLAUDE_CODE_OAUTH_TOKEN, yet usage shows up on a Console organization. What happened?Something higher in the credential order is present on the runner, most often an `ANTHROPIC_API_KEY` in the image or job environment; under `-p` a present key is always used. An `ANTHROPIC_AUTH_TOKEN`, an `apiKeyHelper` in a settings file or a provider switch would also win. Remove it from the job's environment.
- Why does `claude --bare -p` fail to authenticate when only CLAUDE_CODE_OAUTH_TOKEN is set?Bare mode never reads OAuth credentials or the keychain, and that includes `CLAUDE_CODE_OAUTH_TOKEN`. Give a bare run an `ANTHROPIC_API_KEY`, an `apiKeyHelper` in the `--settings` JSON, or a cloud provider's credentials instead.
- claude setup-token saves the token to the keychain like /login
- A setup-token token works on the free claude.ai plan
- The OAuth token outranks an ANTHROPIC_API_KEY on the runner
- --bare mode reads CLAUDE_CODE_OAUTH_TOKEN like any other run
- A setup-token token can start Remote Control sessions
- One person's token is the right secret for every repository