How Claude Code authentication works
Claude Code authentication decides which account pays for and governs each request. In the desktop app you sign in with your account and that is the whole job. In the terminal, the first run of claude opens a browser window, you log in, and you see Login successful. It skips that prompt if you have already approved an API key or signed in earlier with claude auth login. If the browser does not open, press c to copy the login URL.
The trouble starts when a machine has more than one credential on it, which is common for anyone who has ever exported an API key for a side project. Claude Code does not ask which one you meant. It follows a fixed order. Knowing that order fixes most surprise login and billing questions before they become a ticket.
Every Claude Code login method
There are five kinds of account you can authenticate with. Pick by who pays and who needs control.
Claude Code login methods
| Method | How you sign in | Best for |
|---|---|---|
| Pro, Max or Ultra subscription | Browser login with your claude.ai account | Individuals |
| Claude for Teams or Enterprise | Browser login with the claude.ai account your admin invited | Most teams. Teams includes SSO, admin tools and server-managed settings. Enterprise adds domain capture, role-based permissions and the compliance API |
| Claude Console | Browser login with Console credentials after an admin invite | Organizations that want API-based billing |
| Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry | Environment variables set before launch, or the setup wizard behind 3rd-party platform at the login prompt (Bedrock and Google Cloud). No browser login | Companies that already buy through a cloud provider |
| Claude apps gateway | Corporate SSO through /login | Companies that self-host a gateway tied to their identity provider |
My recommendation for a team without a cloud commitment is Claude for Teams or Enterprise. People get Claude Code and Claude on the web on one bill, and you skip handing out and rotating API keys. If procurement already runs through a cloud provider, see the guides for Bedrock, Vertex AI and Microsoft Foundry.
The Console has two roles worth knowing. The Claude Code role can only create Claude Code API keys, while the Developer role can create any kind of API key. Give people the narrower one unless they build on the API. Console users can also sign in without creating a key at all (v2.1.242 or later). Claude Code then keeps a refreshing OAuth login as a profile instead of a static key, which is the better default because there is no long-lived secret sitting on the machine.
Which credential Claude Code uses first
When several credentials are present, Claude Code uses the first one it finds in this order:
- Cloud provider credentials, when CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX or CLAUDE_CODE_USE_FOUNDRY is set.
- ANTHROPIC_AUTH_TOKEN, sent as a bearer token. This is for gateways and proxies.
- ANTHROPIC_API_KEY, sent as the X-Api-Key header. In an interactive session you approve it once and the choice is remembered. In non-interactive mode (-p) it is always used when present.
- The output of your apiKeyHelper script, for rotating credentials such as short-lived tokens from a vault.
- CLAUDE_CODE_OAUTH_TOKEN, the long-lived token from claude setup-token.
- Anthropic profile and federation credentials, the ones used by the ant CLI and Workload Identity Federation. A profile written by ant auth login only ranks here when you name it in ANTHROPIC_PROFILE. Otherwise it ranks below /login.
- Your subscription login from /login. This is the default for Pro, Max, Ultra, Team and Enterprise users.
A signed-in Claude apps gateway session sits outside this list and outranks all of it. When one exists, the CLI uses the gateway token even if a cloud provider variable is set.
Two limits on this order are worth remembering. Claude Desktop and cloud sessions do not read these environment variables or call apiKeyHelper. They use OAuth, unless a desktop session runs a third-party inference configuration, which uses that configuration's credential. And cloud sessions always use your subscription, even if you put an API key in the cloud environment. So a setup that works in the terminal can behave differently in the desktop app, and that is expected.
How to lock Claude Code login to your organization
An admin controls sign-in with three managed settings: forceLoginMethod chooses the kind of login, forceLoginOrgUUID requires claude.ai logins to belong to your organization, and allowedProviders (v2.1.285 or later) lists which services a managed machine may reach Claude through. A typical policy sets forceLoginMethod to "claudeai", forceLoginOrgUUID to a list holding your organization ID, and allowedProviders to "anthropic" and "bedrock".
- Find your organization ID in claude.ai admin settings.
- Deploy the keys through your device management tooling. A developer only receives server-managed settings after authenticating into your organization, so those cannot redirect a first login. See Claude Code managed settings for delivery on each operating system.
- If you also distribute server-managed settings from claude.ai, set both login keys there too until every client runs v2.1.299 or later.
- To allow an LLM gateway, add "customEndpoint" to allowedProviders and set the gateway URL in the managed env block of the same source.
- Test on one managed machine with a personal account and with an API key in the shell. Both should be refused at startup.
These settings block ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN and apiKeyHelper at startup, because organization membership cannot be verified for those credentials. That part works the way you would hope. The gaps below are the part most rollouts miss.
Where the login controls stop
| Gap | What actually happens | What I would do |
|---|---|---|
| The terminal login screen | It pre-selects the method in forceLoginMethod without enforcing it, so a developer can still complete a Console login there | Do not hand out Console invites to people who do not need them, and review the Members page |
| Console logins | forceLoginOrgUUID only pre-selects the organization on the Console sign-in page. It does not check which organization the credential belongs to | Treat this as a convenience, not a control, and audit Console membership |
| claude setup-token and /install-github-app | They enforce only forceLoginMethod, so they can mint a token in a different organization | Decide who may run them and write that into your policy |
| Anthropic profiles and federation credentials | They are not blocked unless an API key style credential is also on the machine, and the keys do not check which organization the profile belongs to | Check /status on a sample of machines. A Profile row names the source |
| allowedProviders set only in server-managed settings | It reaches only sessions that fetch your organization's settings | Deliver it with device management. Keep the server-managed copy for machines you cannot reach |
| Gateway sign-in | forceLoginOrgUUID does not apply because the gateway does not authenticate against an Anthropic organization | Restrict access in your gateway's identity provider, and keep the login keys out of the settings the gateway serves |
Authentication for CI, scripts and unattended runs
For CI and scripts where nobody can click a browser, run claude setup-token. It uses the same browser approval as /login and prints a one-year OAuth token. It does not save the token anywhere, so copy it and set it as CLAUDE_CODE_OAUTH_TOKEN wherever the job runs, using your CI's secret store. It needs a Pro, Max, Ultra, Team or Enterprise plan.
- The token only makes model requests. It cannot start Remote Control sessions or fetch claude.ai connectors. MCP servers you configure locally still work.
- Bare mode does not read CLAUDE_CODE_OAUTH_TOKEN. If your script passes --bare, use ANTHROPIC_API_KEY or apiKeyHelper instead.
- If you use apiKeyHelper, keep the script fast. Past 10 seconds, Claude Code shows a warning in the prompt bar. If the script errors, times out or prints nothing, requests fail within three attempts.
- A /login credential warns you at startup when it is within three days of expiring. Renew early for unattended sessions, because a background or Remote Control session that outlives its login stops making progress until you sign in again.
My take: use one token per job and record who generated it, because it lasts a year and is tied to that person's plan. For wiring it into a pipeline, see Claude Code GitHub Actions and headless mode.
Where credentials are stored and using two accounts
Where Claude Code stores credentials
| System | Location |
|---|---|
| macOS | The encrypted macOS Keychain. If the Keychain rejects the write, such as when it is locked in an SSH session, the login goes in ~/.claude/.credentials.json with file mode 0600 |
| Linux | ~/.claude/.credentials.json with file mode 0600 |
| Windows | %USERPROFILE%\.claude\.credentials.json, restricted to your user account by default through your profile directory's access controls |
To stay signed in to a work and a personal account at once, give each its own configuration directory with CLAUDE_CONFIG_DIR. An alias such as claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude' in your shell profile does it, and each directory keeps its own settings, session history and login. The exception is a Console sign-in without an API key, which is stored outside that directory, so two of those do not stay separate.
Fix common Claude Code login problems
Symptoms and fixes
| What you see | Likely cause | Fix |
|---|---|---|
| Auth errors even though your subscription is active | ANTHROPIC_API_KEY is set and belongs to a disabled or expired organization | Run unset ANTHROPIC_API_KEY, then check /status |
| Login prompt appears after you already signed in | Expired sign-in, an organization or login method your admin requires, or a version before v2.1.290 | Log in again with the account your admin requires, or update Claude Code |
| Login expired, please run /login | The stored login expired and could not be refreshed | Run /login. /status shows the expired login's organization and email |
| Your apiKeyHelper script is failing | The script errored, timed out or printed nothing | Run the script by hand and fix what it prints |
| Connectors or /schedule are missing | A profile or federation source is selected, and those features need your claude.ai login | Unset ANTHROPIC_PROFILE or either federation variable. For an active profile, run /logout or ant auth logout depending on how it was created |
| Your login does not stick after /login | CLAUDE_CODE_OAUTH_TOKEN is still set, so the switch only lasts for that session | Remove the variable from your shell profile and any settings file that sets it |
To start over, type /logout at the prompt. It also resets your first-launch setup, so the next run walks you through login and setup again.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
How do I log in to Claude Code?
Sign in through the desktop app, or run claude in a terminal and complete the browser login with a Pro, Max, Ultra, Team, Enterprise or Console account. Bedrock, Google Cloud and Foundry use environment variables instead of a browser login.
Does ANTHROPIC_API_KEY override my Claude subscription?
Yes, once you approve it. The API key ranks above your /login subscription credential. In non-interactive mode it is used whenever it is present. Run unset ANTHROPIC_API_KEY to fall back to your subscription and check /status to confirm.
How do I check which credential Claude Code is using?
Run /status. It shows the active login method, and when a login and an API key are both configured it marks the one that is not in use. If a profile is the source, a Profile row names it.
Does Claude Code support SSO?
Yes. Claude for Teams and Enterprise include SSO, the Console can be set up with SSO, and a self-hosted Claude apps gateway signs developers in with corporate SSO through your identity provider.
How do I authenticate Claude Code in CI?
Generate a one-year OAuth token with claude setup-token and set it as CLAUDE_CODE_OAUTH_TOKEN from your secret store, or use ANTHROPIC_API_KEY. In bare mode the OAuth token is not read, so use an API key or apiKeyHelper.
Can I stop developers logging in with personal accounts?
Set forceLoginMethod and forceLoginOrgUUID in managed settings and deploy them through device management. Claude Code then refuses claude.ai logins from other organizations. Console logins and claude setup-token have gaps, so test them on a managed machine.
Last reviewed by David Iya on November 8, 2026
