Claude Code login: subscription or API key

Which credential is your Claude Code session using?

A Claude Code login works one of two ways. You sign in with a Claude subscription account from claude.ai, or you authenticate against an Anthropic Console organisation, which meters every token against that organisation's API (application programming interface) balance. Run /status inside a running session to see which one is active: the Status tab shows a Login method row for the account you signed in with, and an extra API key row appears when an API key is supplying the credential instead.

Whether the tool is covered by your plan at all is a separate question, answered in whether Claude Code is included with a Claude Pro subscription, and the mechanics of keys against the Claude API are covered in how Claude API authentication works. What follows is the part those two do not cover: which credential a session actually picked, and how to change it.

The behaviour below comes from Anthropic's Claude Code authentication documentation, read on 31 August 2026. Claude Code ships often and several of these behaviours name a minimum version, so run claude --version before you decide your machine is broken.

Two accounts that can share one email address

A claude.ai account and a Claude Console account at platform.claude.com are different accounts. They can carry the same email address and still be separate sign-ins with separate balances, in separate organisations. Creating one does not create the other. Paying for a Max plan puts no credit on a Console organisation, and topping up a Console organisation adds nothing to your plan.

The balances differ because the billing models differ. A subscription login draws on your plan's usage allowance, which resets on a rolling five hour window and a weekly window, and that allowance is shared with Claude on the web. A Console credential is billed per token to the organisation, and the authoritative figures live on the Console usage page. What that difference costs over real work is the subject of paying per token against paying for a subscription.

One account type cannot take the subscription path at all. Anthropic lists the accounts you can log in with as a Pro or Max subscription, a Claude for Teams or Enterprise seat, a Claude Console account, and a cloud provider. A free claude.ai account is not on that list, so a free-plan user has no subscription credential to log in with, and what the free Claude tier does and does not include does not stretch to the command line tool. The remaining route is a Console organisation with API credit, which is a paid account of a different shape.

Path one: sign in with your Claude subscription

Run claude in a project directory. On first launch it opens a browser window for you to sign in with the claude.ai account that holds your plan.

claude

Two things behave differently on a server. If the browser does not open, press c to copy the login URL to your clipboard and paste it into a browser on your own machine. If that browser then shows a login code instead of returning you to the terminal, paste the code back at the prompt asking for it. That second case is normal over SSH (secure shell), in WSL2 and inside containers, because the browser cannot reach the local callback server that Claude Code started on the remote machine.

When the login finishes, check it instead of assuming it. Start a session and run /status. The Status tab names the login method, plus the organisation and email address it saved. /login runs the flow again against a different account, and /logout removes the stored credential. Logging out also resets the first-run setup state, so the next claude walks you through onboarding again.

Knowing where that credential lands matters when you rebuild a box or hand one over:

• Linux: ~/.claude/.credentials.json, file mode 0600.
• macOS: the encrypted Keychain. When the Keychain rejects the write, which happens when it is locked in an SSH session, Claude Code falls back to the same 0600 file.
• Windows: %USERPROFILE%\.claude\.credentials.json, restricted to your user by the profile directory's own access controls.
• Any platform with CLAUDE_CONFIG_DIR set: the file moves under that directory, and the macOS Keychain entry is keyed to it, so a session started with a different CLAUDE_CONFIG_DIR reads a different credential.

Claude Code manages that file through /login and /logout. Editing it by hand is not a supported way to switch accounts.

Path two: authenticate against a Console organisation

Console access starts with an administrator. They invite you from the Console under Settings, then Members, then Invite. They also assign a role: the Claude Code role can create only Claude Code API keys, while the Developer role can create any key. You then choose the Anthropic Console account at the /login prompt.

From Claude Code v2.1.242 there are two Console routes, and they store different things. Signing in with your Console account keeps the OAuth (open authorisation) token from that browser sign-in and stores it as an Anthropic profile, creating no API key at all. Claude Code refreshes that login on its own, and when the refresh fails, requests fail until you sign in again. Creating an API key, which the prompt labels legacy, mints a Console key and stores it with your other credentials. A static key never refreshes, so it keeps working until someone revokes it. That is useful on a build server and a liability on a laptop.

Unset ANTHROPIC_API_KEY before you start a keyless Console sign-in. With that variable set, Claude Code skips the login prompt entirely and asks you to approve the key it found instead.

You do not always get the choice. Claude Code creates a key without asking when the session runs against a cloud provider, when any settings file sets forceLoginOrgUUID or pins forceLoginMethod to "claudeai" or "console", or when a managed settings source exists on the machine and Claude Code cannot read it. Those are administrator decisions, so if the keyless option never appears for you, ask whoever manages the fleet. /status also prints a Setting sources line naming every settings file the session loaded, and it names the managed source when one applies to you.

The first time you authenticate Claude Code against a Console organisation, the Console creates a workspace named "Claude Code" for it. That workspace exists so Claude Code spend is tracked in one place, and you cannot create API keys inside it.

Why ANTHROPIC_API_KEY wins after you have logged in

Claude Code never asks which credential you would prefer. It checks sources in a fixed order and takes the first one it finds. As documented in August 2026, that order is:

1. Cloud provider credentials, when CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX or CLAUDE_CODE_USE_FOUNDRY is set.
2. ANTHROPIC_AUTH_TOKEN, sent as an Authorization: Bearer header, for gateways that authenticate with bearer tokens.
3. ANTHROPIC_API_KEY, sent as the X-Api-Key header.
4. The output of an apiKeyHelper script named in a settings file.
5. CLAUDE_CODE_OAUTH_TOKEN, the long-lived token from claude setup-token.
6. Anthropic profile and federation credentials.
7. The subscription credential written by /login.

Your subscription login is last. So an ANTHROPIC_API_KEY exported anywhere in the process environment outranks the account you signed in with, and the session bills a Console organisation while you believe it is drawing on your plan. Nothing is broken. The order is doing what it documents, which is why nothing warns you.

Two details make this easy to miss. In an interactive session, Claude Code asks once whether to use the key it found and remembers your answer, so a choice you made a month ago still applies today. In non-interactive mode with -p, there is no prompt at all and the key is always used when it is present. -p is the mode a cron job or a CI (continuous integration) step runs in, so an unattended job is exactly where the wrong credential goes unnoticed longest.

There is a fast visual check inside the session. While ANTHROPIC_API_KEY is set, /config shows a "Use custom API key" toggle. The toggle exists only while the variable is set, so its absence means the environment is clean.

Finding the stray key on a server

An exported key survives in more places than a shell profile:

• ~/.bashrc, ~/.bash_profile, ~/.profile or ~/.zshrc, read by every new login shell.
• A systemd unit, through Environment= or EnvironmentFile=, for anything you run as a service.
• The tmux server, which keeps a copy of the environment it was started with. A pane you open today can inherit a variable you deleted from your profile last week, because the server has been running since before the edit.
• A container image or CI job definition, where the variable is set outside any file you can read from inside the shell.
• The env block of a Claude Code settings file, which is an ordinary settings key and follows the normal settings precedence.

Check them before you spend anything else:

[ -n "$ANTHROPIC_API_KEY" ] && echo "ANTHROPIC_API_KEY is set" || echo "not set"
env | grep -E '^(ANTHROPIC_|CLAUDE_CODE_)' | cut -d= -f1
grep -n 'ANTHROPIC_API_KEY' ~/.bashrc ~/.bash_profile ~/.profile ~/.zshrc 2>/dev/null
tmux show-environment 2>/dev/null | grep ANTHROPIC
grep -n 'ANTHROPIC_API_KEY\|apiKeyHelper' ~/.claude/settings.json .claude/settings.json .claude/settings.local.json 2>/dev/null

The second command pipes through cut on purpose, so it prints variable names without printing the secret values onto a screen you may be sharing or recording. The first command decides the question: if it says the variable is set, the next claude you start from this shell uses that key. Silence from all five means no environment credential exists, so a session started here falls through to your /login credential.

Add systemctl cat your-unit.service | grep -i environment for any service that runs Claude Code, since a unit file sets its own environment and never reads your shell profile.

Switching a session from one credential to the other

To move back to your subscription:

unset ANTHROPIC_API_KEY
[ -n "$ANTHROPIC_API_KEY" ] && echo "still set" || echo "clear"
claude

Expect clear, then run /status in the new session and confirm the API key row has gone. Unsetting the variable in your shell does nothing to a Claude Code process that is already running, because a process keeps the environment it was started with. Restart the session.

Then delete the export from whichever file set it, or the next login shell puts it back. Inside tmux, tmux set-environment -u ANTHROPIC_API_KEY clears it for panes opened after that point in the session, while panes already open keep their own copy.

To move the other way, set ANTHROPIC_API_KEY in the environment, or run /login and pick the Console account. To clear a stored login completely, run /logout. After a keyless Console sign-in, /logout removes and revokes the credential that sign-in wrote.

If /status still disagrees with what you expect, run claude doctor. It lists the settings entries Claude Code rejected, which catches a settings file that failed to parse and therefore never applied at all.

Authenticating where there is no browser

claude setup-token opens the same browser authorisation flow as /login and prints a one-year OAuth token to the terminal.

claude setup-token

It saves the token nowhere, so copy it when it appears. Set it as CLAUDE_CODE_OAUTH_TOKEN on the machine that needs it. The token authenticates with your subscription, so it needs a Pro, Max, Team or Enterprise plan, and it can only make model requests. Bare mode does not read it, so a script that passes --bare needs ANTHROPIC_API_KEY or an apiKeyHelper instead.

Precedence bites here too. If CLAUDE_CODE_OAUTH_TOKEN lives in a shell profile, running /login switches the current session to the new login, and every new session reads the variable again until you remove it.

If your organisation runs inference through Amazon Bedrock, Google Cloud or Microsoft Foundry, those credentials sit at the top of the order and no browser login happens at all. Setting that up is a separate job, covered in running Claude Code against Bedrock or Vertex.

A long-lived session on a VPS (virtual private server) is where these problems concentrate, because the shell that started it may have been configured months ago and never restarted since. Running Claude Code on a VPS inside tmux covers the session side of that setup.

Checking what each credential actually spent

On a subscription login, /usage shows your plan usage bars and a breakdown of what consumed them. The dollar figure in its Session block is computed locally from token counts at list price, so treat it as an estimate aimed at API users rather than as a bill. Subscribers should read the bars, not the dollars.

On a Console credential, the numbers that matter live in the Console: the usage page for spend, and the Claude Code dashboard for per-member figures. Nothing printed in your terminal is authoritative for that billing.

If the plan bars never move while you work, an environment credential is winning the order. That single symptom is the most reliable sign that the wrong credential is in effect, and tracking what a Claude Code session spends goes further into measuring it. When the bars do move and then stop, you have hit a plan ceiling instead, which how Claude usage limits and reset windows work explains.

Failure modes and what to look for

Everything works, but your plan usage never changes. An environment credential is in effect. /status shows an API key row, and the shell check above shows the variable.

Requests fail although your subscription is healthy. A key belonging to a disabled or expired Console organisation is outranking your login. Run unset ANTHROPIC_API_KEY, start a new session, and check /status again.

A warning at startup that your login is expiring. Recent versions warn when a /login credential is within three days of expiry, and /status then shows the login row in an expired state with the organisation and email it saved. Run /login to renew. The warning never blocks a request, which is why it is easy to ignore until an unattended session stops making progress.

An apiKeyHelper that is slow or failing. Claude Code re-runs the helper every five minutes by default, tunable with CLAUDE_CODE_API_KEY_HELPER_TTL_MS, and shows a notice in the prompt bar when a run takes longer than ten seconds. A helper that returns no key, whether it errored or timed out, causes request failures within three attempts.

The right credential, the wrong organisation. One email address can belong to two organisations. /status names the organisation it authenticated into, so read that line rather than assuming which one you landed in.

FAQ

How do I tell which account Claude Code is using right now?

Run /status in the session. The Status tab shows a Login method row for the account you signed in with, and adds an API key row when an API key is supplying the credential. A Profile row replaces the login row when an Anthropic profile or a federation credential is selected instead. Outside the session, checking whether ANTHROPIC_API_KEY is set in your shell tells you whether an environment credential exists that would outrank your login.

Why is my Claude Pro or Max subscription being ignored?

Because an environment credential outranks it. Claude Code takes the first credential it finds in a fixed order, and the /login subscription credential is last, below the cloud provider variables, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper and CLAUDE_CODE_OAUTH_TOKEN. Run unset ANTHROPIC_API_KEY, start a new session, and confirm with /status. Then remove the export from the shell profile, systemd unit, tmux environment or container definition that set it, or it returns on the next login shell.

Can I use Claude Code with a free Claude account?

No. The account types Anthropic lists for login are a Pro or Max subscription, a Claude for Teams or Enterprise seat, a Claude Console account, and a cloud provider. A free claude.ai account is not one of them, so there is no subscription credential for it to store. The paid alternative to a subscription is a Claude Console organisation with API credit, billed per token, which is a separate account even when it carries the same email address.

Do my claude.ai account and my Console account share one balance?

No. They are separate accounts with separate billing, even when both use the same email address. Subscription usage draws on your plan allowance, which is shared with Claude on the web and resets on a rolling five hour window and a weekly window. Console usage is billed per token to the organisation and appears on the Console usage page. Adding credit to one does nothing for the other.

How do I authenticate Claude Code on a headless server?

Two options. Run claude over SSH and finish the browser login on your own machine: press c to copy the URL, sign in there, then paste the code back into the terminal if the browser shows one instead of redirecting. Or run claude setup-token on a machine that has a browser, copy the one-year token it prints, and set it as CLAUDE_CODE_OAUTH_TOKEN on the server. That token needs a Pro, Max, Team or Enterprise plan and can only make model requests, so a script using --bare needs an API key or an apiKeyHelper instead.