Authentication

Before Claude Code can do anything it needs a credential. For most people that is a browser login with a claude.ai account, but teams also use Console accounts, cloud providers, gateways, static API keys and long-lived tokens for CI. This page covers each route, how admins can pin people to the right one, and the order Claude Code uses when more than one credential is lying around.

Logging in for the first time

Run claude after installing. On first launch it opens a browser for you to sign in. A few things that help when it does not go smoothly:

• No browser appeared? Press c to copy the login URL and paste it into a browser yourself.
• Browser shows a code instead of returning to the terminal? Paste it at the Paste code here if prompted prompt. This happens when the browser cannot reach Claude Code's local callback, which is normal over SSH, in containers and often in WSL2.
• Using an API key? If ANTHROPIC_API_KEY is set and you approve it when asked, the login step is skipped altogether.

When you see Login successful, press Enter and you are in.

Which account types work

/logout signs you out and also resets first-run setup, so the next claude walks you through login again.

Keeping work and personal accounts apart

Each configuration directory carries its own settings, history and credentials, so the cleanest way to run two accounts is two directories. I use an alias:

# ~/.zshrc
alias claude-client='CLAUDE_CONFIG_DIR=~/.claude-client claude'

The first run of claude-client prompts for a fresh login, and plain claude keeps your usual account. One exception: keyless Console sign-ins are stored outside the config directory, so two of those will not stay separate this way.

Team access

The options, roughly in order of how often I recommend them:

1. Claude for Teams or Enterprise. One subscription covers Claude Code and claude.ai, with central billing. Teams is self-service and includes SSO, admin tools and server-managed settings. Enterprise adds domain capture, role-based permissions and the compliance API. Subscribe, invite people from the admin dashboard, and they log in with their claude.ai accounts.
2. Claude Console. Suits API-billed organisations. Invite people in bulk under Settings > Members > Invite or set up SSO. Give each person a role: Claude Code (can only create Claude Code API keys) or Developer (any API key). Each person accepts the invite, installs Claude Code and logs in with their Console credentials.
3. Claude apps gateway. A self-hosted gateway that signs developers in through your IdP and forwards to the cloud provider you choose.
4. Cloud providers. Follow the Bedrock, Vertex AI or Foundry page, then hand out the environment variables and credential instructions (typically via settings).

Console sign-in without an API key

From v2.1.242, choosing the Console account at /login offers two routes:

• Sign in with your Console account (recommended) stores an OAuth token as an Anthropic profile and creates no API key. Claude Code refreshes it automatically; if refresh fails you see "Anthropic profile login expired" until you sign in again.
• Create an API key (legacy) makes a static Console key and stores it.

You will not be offered the choice (a key is created automatically) when you run against a cloud provider or Claude Platform on AWS, when any settings file sets forceLoginOrgUUID or sets forceLoginMethod to "claudeai" or "console", or when a managed settings source exists but cannot be read and nothing else supplies policy. Unset ANTHROPIC_API_KEY before using the keyless route.

The keyless sign-in writes the profile named by ANTHROPIC_PROFILE, otherwise your active profile, otherwise default. It refuses to overwrite a federation profile, signs you out of any claude.ai login on the machine, and /logout revokes it. Server-managed settings apply to it from v2.1.257.

Restricting logins to your organisation

Two managed keys keep people on the right account:

• forceLoginMethod: "claudeai", "console" or "gateway".
• forceLoginOrgUUID: one or more organisation IDs. For Teams and Enterprise you find yours in the claude.ai organisation admin settings.

For claude.ai logins, Claude Code rejects any other organisation and exits at startup if the active credential belongs to one not on the list. For Console logins, a single Console organisation ID just pre-selects that organisation on the sign-in page; Claude Code does not check which organisation the resulting credential belongs to.

How each login path treats the keys (v2.1.212 and later):

Setting forceLoginOrgUUID anywhere also switches off the keyless Console route described above.

These keys also govern sessions that do not use a login:

• ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN or apiKeyHelper: blocked at startup, because organisation membership cannot be proven.
• Cloud provider sessions: allowed, unless one of those credentials (or a key saved by an earlier Console login) is also on the machine.
• Anthropic profiles and federation credentials: allowed under the same condition. Their organisation is not checked.

Warning: Deploy these keys through device management, not only server-managed settings. Server-managed settings reach only accounts already signed in to your organisation, so they cannot steer a first login. If you use both, put the keys in both, because cached server-managed settings replace the device file and these keys are not among the per-key exceptions. In a gateway deployment, keep them out of the settings the gateway serves.

Restricting providers

allowedProviders (v2.1.285+) limits which services a managed machine may reach Claude through. It complements the login keys, which only govern which Anthropic account is used.

{
  "forceLoginMethod": "claudeai",
  "forceLoginOrgUUID": ["5d0c2b9e-1111-4a2b-9c3d-000000000000"],
  "allowedProviders": ["anthropic", "vertex"]
}

With that policy, people on your claude.ai organisation or on Vertex AI start normally. Anything else is refused at startup, and a running session that switches provider is refused on its next request. To allow an LLM gateway, list "customEndpoint" and pin the gateway URL in the managed env block of the same source. A list set only in server-managed settings reaches only sessions that fetch those settings, so treat that as a convenience rather than enforcement. The settings reference lists every accepted value.

Where credentials are stored

With CLAUDE_CONFIG_DIR set, the credentials file moves under that directory and the macOS Keychain entry is keyed to it. Leave the file to /login and /logout; to send traffic elsewhere use ANTHROPIC_BASE_URL.

Credential helper scripts

The apiKeyHelper setting runs a script that prints a key, which is how you plug in a vault or a short-lived token service. If the script takes more than 10 seconds you get a timing notice in the prompt bar. If it errors, times out or prints nothing, requests fail with "Your apiKeyHelper script is failing" within three attempts.

apiKeyHelper, ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN apply to the CLI and things that wrap it: the VS Code extension, the Agent SDK and GitHub Actions. Claude Desktop and cloud sessions ignore them and use OAuth, apart from desktop sessions running a third-party inference configuration.

Expiring logins

Within three days of a /login credential expiring you see Your login expires in 3 days · run /login to renew at startup. It never blocks anything. Once the login really expires and cannot refresh, every request fails with Login expired · Please run /login. From v2.1.210 /status shows a Login row marking the login as expired and telling you to log in again. Renew early if you rely on agent view background sessions or Remote Control, because they stall once the credential lapses.

Which credential wins

When several are present, Claude Code takes the first match in this list:

A signed-in Claude apps gateway sits outside this list and beats all of it, cloud providers included. If managed settings set forceLoginMethod to "gateway" or set forceLoginGatewayUrl, and no cloud provider variable is set, only the gateway sign-in is used (v2.1.261+, or v2.1.265+ when only forceLoginGatewayUrl is set).

The classic trap: you have a subscription but an old ANTHROPIC_API_KEY in your shell profile, you approve it, and requests fail because the key's organisation is disabled. unset ANTHROPIC_API_KEY, then check /status, which marks any credential that is configured but not in use.

Cloud sessions always use your subscription, whatever keys you put in the cloud environment.

Anthropic profiles and federation

A profile is a named credential file in your Anthropic configuration directory (~/.config/anthropic on macOS and Linux, %APPDATA%\Anthropic on Windows). Its auth mode is oidc_federation for Workload Identity Federation, or user_oauth when written by ant auth login or a keyless Console sign-in. Claude Code stops at the first of these that is set:

Supporting variables such as ANTHROPIC_IDENTITY_TOKEN_FILE are read during the token exchange. Profiles are ignored in bare mode, Claude Desktop and cloud sessions. When one is chosen, /status shows a Profile row instead of Login method, and claude.ai-only features (claude.ai connectors, /schedule) are unavailable. To stop a profile being chosen, unset the variables, or use /logout, ant auth logout, or delete the profile file from configs/.

Tokens for CI and scripts

Where no browser is available, mint a one-year OAuth token:

claude setup-token

You approve in the browser, the token prints once and is not saved. Put it in CLAUDE_CODE_OAUTH_TOKEN in your CI secret store. It needs a Pro, Max, Team or Enterprise plan and can only make model requests, so Remote Control and claude.ai connectors will not work with it; locally configured MCP servers are fine.

If you later run /login while the variable is set, the current session switches to the new login, but every new session reads the variable again until you remove it. --bare mode does not read CLAUDE_CODE_OAUTH_TOKEN at all; use ANTHROPIC_API_KEY or apiKeyHelper there.

Related

• Advanced setup
• Managed settings
• Troubleshooting installation
• Headless mode
• LLM gateway