Claude Code authentication: subscriptions, API keys, and cloud providers

Claude Code authenticates with a Claude subscription login (Pro, Max, Team, or Enterprise), a Claude Console account billed at API rates, or cloud-provider credentials for Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, or Claude Platform on AWS. When several credentials are present, a fixed precedence order decides which one is used, and /status shows the active method.

This page is for developers who are logging in for the first time, on a laptop, over SSH, or in CI. Tech leads who standardize the login for a team will find the organization controls near the end. A typical failure looks like this: you pay for Max, but your shell profile still exports ANTHROPIC_API_KEY from a side project, so every session bills that key instead. Or your pipeline has no browser, and the first job that runs claude hangs at a login prompt.

What you’ll walk away with from Claude Code authentication

• A working login for the billing model you actually want, verified by a command rather than by a hopeful prompt.
• The precedence order that decides which credential wins, and a prompt that audits your machine for conflicts.
• A browser-free token for CI and a rotating-key helper for vault-backed setups.
• Managed settings that keep a team’s logins inside one organization, with the gaps those settings leave.

All commands on this page were checked against the installed CLI, Claude Code 2.1.283 (claude --help, claude auth --help), and the official authentication documentation on 2026-09-26.

Which Claude Code login method should you choose?

Choose by who pays and who administers access. The login flow is the easy part.

Method	Choose it when	Billing	How you sign in
Claude Pro or Max	You are an individual developer	Flat monthly plan with rolling 5-hour and weekly usage windows	claude, then Claude account with subscription
Claude for Teams or Enterprise	Your company wants one bill, seats, and SSO	Per seat; Enterprise adds usage at API rates	claude with the claude.ai account your admin invited
Claude Console	You want pay-per-token billing and per-workspace cost tracking	Tokens at API rates	claude auth login --console, or ANTHROPIC_API_KEY
Amazon Bedrock	AI traffic must stay on your AWS account	AWS bill	Setup wizard or CLAUDE_CODE_USE_BEDROCK=1
Google Cloud’s Agent Platform (formerly Vertex AI)	AI traffic must stay on your Google Cloud project	Google Cloud bill	Setup wizard or CLAUDE_CODE_USE_VERTEX=1
Microsoft Foundry	AI traffic must stay on Azure	Azure bill	CLAUDE_CODE_USE_FOUNDRY=1 (no wizard)
Claude Platform on AWS	You buy Anthropic’s platform through AWS	AWS bill	CLAUDE_CODE_USE_ANTHROPIC_AWS=1

The free Claude plan does not include Claude Code. As of 2026-09-26 the published plan prices are Pro $20 per month, Max 5x $100, and Max 20x $200; Team and Enterprise are priced per seat (claude.com/pricing). For what each option costs under agent workloads, see Claude Code cost control. If your company routes all model traffic through its own proxy, read LLM gateway configuration instead of this page.

The default model depends on how you log in

From v2.1.280, on both release channels (checked 2026-10-12), Claude Code defaults to Claude Opus 5.5 on every paid plan, the Anthropic API, Bedrock, Google Cloud’s Agent Platform, and Claude Platform on AWS. Microsoft Foundry defaults to Claude Sonnet 4.5, which Anthropic retires on 2026-11-30 on Anthropic-operated platforms (model deprecations page, checked 2026-10-12). The models hub keeps the current table.

Log in with a Claude subscription

This is the default path for Pro, Max, Team, and Enterprise users.

1. In your terminal, start Claude Code:

   claude

   To sign in without opening a session, run claude auth login instead. It uses the Claude subscription by default; add --sso to force your company’s SSO flow or --email you@example.com to pre-fill the login page.

2. Choose Claude account with subscription at the login prompt. A browser window opens. If it does not, press c to copy the login URL and paste it into any browser.

3. Sign in. If the browser shows a code instead of returning to the terminal, paste the code at the Paste code here if prompted prompt. This happens over SSH, in WSL2, and in containers, where the browser cannot reach Claude Code’s local callback server.

4. Wait for Login successful, then press Enter.

5. Confirm what you are logged in as from the terminal:

   claude auth status --text

   Inside a session, /status shows the same information, including the login method, organization, and email.

Team and Enterprise members use the same flow with the claude.ai account their admin invited. Enterprise adds domain capture, role-based permissions, and the compliance API on top of Teams.

Use a Claude Console account for API billing

Console billing charges per token, which suits bursty usage and teams that already track spend in the Console. An admin must invite you to the Console organization first, with either the Claude Code role (can create only Claude Code keys) or the Developer role.

claude auth login --console

From v2.1.242, the Console login (Anthropic Console account at the login prompt, or claude auth login --console) asks how to sign in:

• Sign in with your Console account (labeled recommended) stores a refreshable OAuth login and creates no API key. Prefer it: there is no static secret on disk to leak.
• Create an API key (labeled legacy) creates a key and stores it with your other credentials.

The keyless sign-in also signs you out of any claude.ai login stored on the machine, so do not use it on a laptop where you want to keep your subscription login; /logout removes and revokes the credential it wrote.

Claude Code skips that choice and always creates a key when you run against a cloud provider or when a settings file sets forceLoginOrgUUID or forceLoginMethod to "claudeai" or "console", or when a managed settings source on the machine exists but can’t be read. Unset ANTHROPIC_API_KEY before you sign in without a key.

You can also supply a key directly through ANTHROPIC_API_KEY. In an interactive session, Claude Code asks you once to approve the key and remembers the answer; the “Use custom API key” toggle in /config changes it later. With claude -p, the key is always used when present. Load the key from your secret manager rather than writing it into ~/.zshrc, or use apiKeyHelper.

Configure a cloud provider

With a cloud provider, no browser login is needed. Your provider’s own credentials authenticate, and requests are billed to your cloud account. For Bedrock and Google Cloud’s Agent Platform, the easiest path is the wizard: run claude, choose 3rd-party platform at the login prompt, and pick your provider. The wizard detects your credentials, asks for a region, checks which Claude models you can invoke, and saves the result to the env block of ~/.claude/settings.json.

Amazon Bedrock

First enable an Anthropic model in the Bedrock console’s model catalog and submit the use-case form. Then either run the wizard (reopen it later with /setup-bedrock; until CLAUDE_CODE_USE_BEDROCK=1 is set the command is hidden from the menu, so type it in full) or set the variables yourself:

# Terminal: sign in with an IAM Identity Center profile, then point Claude Code at Bedrock
aws sso login --profile YOUR_PROFILE
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_PROFILE=YOUR_PROFILE
export AWS_REGION=us-east-1   # optional when the profile already sets a region
claude

YOUR_PROFILE is the profile name in ~/.aws/config. Prefer a profile over static AWS_ACCESS_KEY_ID exports. To renew an expired SSO session automatically, add "awsAuthRefresh": "aws sso login --profile YOUR_PROFILE" to your settings; Claude Code runs it only when your credentials look expired and an STS GetCallerIdentity check confirms it.

Google Cloud's Agent Platform

Enable the API for your project and request access to the Claude models in Model Garden. Then run the wizard (reopen it with /setup-vertex) or set the variables. The environment variables still use the old “Vertex” name:

# Terminal: Application Default Credentials, then point Claude Code at your project
gcloud auth application-default login
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR_PROJECT_ID
claude

global gives the widest model availability. For a model that is not served on the global endpoint, keep global and override that one model’s region, for example export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5.

Microsoft Foundry

Foundry has no setup wizard (checked against Claude Code 2.1.283 on 2026-09-26), so the environment variables are the only configuration path:

# Terminal: Entra ID through the Azure default credential chain
az login
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=YOUR_RESOURCE_NAME
claude

YOUR_RESOURCE_NAME is your Azure resource name; Claude Code builds the endpoint URL from it. If you cannot use Entra ID, set ANTHROPIC_FOUNDRY_API_KEY from your secret store instead of running az login.

Foundry has no startup model check, so pin ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, and ANTHROPIC_DEFAULT_HAIKU_MODEL to the deployment names you created; otherwise requests fail when a built-in default is not deployed in your resource.

Claude Platform on AWS

# Terminal: SigV4 through your AWS profile
export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
export ANTHROPIC_AWS_WORKSPACE_ID=YOUR_WORKSPACE_ID
export AWS_REGION=us-east-1
export AWS_PROFILE=YOUR_PROFILE
claude

ANTHROPIC_AWS_WORKSPACE_ID is required and starts with wrkspc_. This provider is opt-in even when AWS credentials are present, and Bedrock and Foundry take precedence, so unset CLAUDE_CODE_USE_BEDROCK and CLAUDE_CODE_USE_FOUNDRY first. Without federated AWS credentials, set ANTHROPIC_AWS_API_KEY to a workspace key from the AWS Console (Claude Platform on AWS → API keys); it overrides SigV4.

Run /status after the first prompt: it shows the provider and, for Bedrock, the resolved region, and its source when it came from your AWS config files or the default fallback.

Authenticate Claude Code in CI and on headless machines

A pipeline cannot click through a browser. You have two options:

• A subscription token. Run claude setup-token on your own machine. It opens the same browser flow as /login and prints a one-year OAuth token without saving it. Store the token in your CI secret store as CLAUDE_CODE_OAUTH_TOKEN. It requires a Pro, Max, Team, or Enterprise plan and can only make model requests: it cannot start Remote Control sessions or fetch claude.ai connectors. Keep it out of your laptop’s shell profile: running /login while it is set switches only the current session, and every new session reads the variable again.
• A Console API key. Store it as ANTHROPIC_API_KEY. Use this, or an apiKeyHelper passed with --settings, for any job that runs claude --bare, because bare mode never reads CLAUDE_CODE_OAUTH_TOKEN, the Keychain, or a /login session. A key in a dedicated Console workspace also keeps pipeline spend separate from people’s spend.

Inject the secret only into the step that runs Claude Code. Never let a job that checks out an untrusted pull request run with it in the environment. The CI/CD page has the workflow, and agent identity and secrets covers scoping and rotation.

Copy-paste prompt: add a CI smoke test for Claude Code auth

Add a first step to .github/workflows/claude.yml that proves Claude Code can
authenticate before any expensive job runs. Requirements:
- Job-level `permissions: contents: read` and `persist-credentials: false`
  on checkout.
- Install Claude Code on the runner first (native installer or npm) and
  print `claude --version`, so a missing binary fails separately from a
  failed login.
- Read the credential from the repository secret CLAUDE_CODE_OAUTH_TOKEN
  (or ANTHROPIC_API_KEY if the job uses --bare) and expose it only as an
  env var on this step and the step that runs Claude Code.
- Run `claude -p "Reply with the single word OK"` with a 60-second timeout
  and fail the job if the exit code is non-zero or the output, trimmed and
  compared case-insensitively, does not contain OK.
- Never echo the secret or run `env` unfiltered.
Show me the diff, then explain which failure each check catches.

Which credential does Claude Code use when several are set?

Claude Code picks exactly one credential, in this order:

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 a bearer token (for LLM gateways and proxies).
3. ANTHROPIC_API_KEY, once you approve it in an interactive session.
4. The output of an apiKeyHelper script.
5. CLAUDE_CODE_OAUTH_TOKEN from claude setup-token.
6. Anthropic profile and federation credentials (the ant CLI and Workload Identity Federation). A profile from ant auth login or the keyless Console sign-in ranks here only when ANTHROPIC_PROFILE names it; otherwise it ranks below /login. /status shows a Profile row when one is in use.
7. The subscription login from /login.

A signed-in Claude apps gateway session sits above this list. The practical consequence: anything exported in your shell outranks your subscription. An approved ANTHROPIC_API_KEY bills the Console even though you pay for Max, and a key from a disabled organization makes every request fail. When a login and a key are both configured, /status marks the one that is not in use.

Copy-paste prompt: audit this machine for credential conflicts

Audit how Claude Code authenticates on this machine. Do not print any secret
values, only variable names and file locations.
1. Run `claude auth status --text` and summarise the result.
2. Run `env | cut -d= -f1 | grep -E '^(ANTHROPIC_|CLAUDE_CODE_|AWS_PROFILE|CLOUD_ML_REGION)'`.
3. Search ~/.zshrc, ~/.bashrc, ~/.profile, ~/.config/fish/config.fish and the
   "env" and "apiKeyHelper" keys of ~/.claude/settings.json and
   .claude/settings.json for credential variables.
4. Using Claude Code's precedence order (cloud provider flags, then
   ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper,
   CLAUDE_CODE_OAUTH_TOKEN, profiles, /login; a user_oauth profile from
   `ant auth login` or the keyless Console sign-in ranks above /login only
   when ANTHROPIC_PROFILE names it), tell me which credential wins
   today and which leftovers I should remove. Propose the edits; do not apply them.

Rotate keys from a vault with apiKeyHelper

When keys come from a vault or expire on a schedule, point apiKeyHelper at a script that prints the credential to stdout. Claude Code runs it through /bin/sh (or cmd on Windows) and sends the output as the API key.

{
  "apiKeyHelper": "~/.claude/bin/anthropic-key.sh"
}

Claude Code caches the output and re-runs the script after five minutes (change it with CLAUDE_CODE_API_KEY_HELPER_TTL_MS), after a 401 or 403, and before a request when the cached value is an expired JWT. A helper defined in project settings runs only after you accept the workspace trust prompt. If the script exits non-zero, times out, or prints nothing, requests fail with Your apiKeyHelper script is failing within three attempts.

Copy-paste prompt: write an apiKeyHelper for HashiCorp Vault

Write ~/.claude/bin/anthropic-key.sh for Claude Code's apiKeyHelper.
- POSIX sh, `set -eu`.
- Print only the key from `vault kv get -field=api_key secret/claude-code`
  to stdout, with no trailing text.
- If the command fails or returns an empty value, write a one-line reason to
  stderr and exit 1, so Claude Code reports the helper as failing instead of
  sending an empty key.
- Never log the key. chmod the file to 700.
Then add "apiKeyHelper": "~/.claude/bin/anthropic-key.sh" to
~/.claude/settings.json without touching other keys, and test the script by
running it with stdout piped to `wc -c` so the key is never displayed.

Where does Claude Code store credentials, and how do you switch accounts?

System	Where the login lives
macOS	The encrypted Keychain. If the Keychain is locked (common over SSH), Claude Code falls back to ~/.claude/.credentials.json with mode 0600.
Linux	~/.claude/.credentials.json, mode 0600
Windows	%USERPROFILE%\.claude\.credentials.json, restricted to your user by the profile directory’s permissions

Setting CLAUDE_CONFIG_DIR moves .credentials.json and the settings files under that directory, and on macOS it keys a separate Keychain entry. That makes it the clean way to keep a personal and a work account side by side:

# ~/.zshrc: a second command that uses its own login and settings
alias claude-work='CLAUDE_CONFIG_DIR="$HOME/.claude-work" claude'

Run claude-work once and log in with the work account. To switch the account for a single configuration instead, type /login in a session; /logout signs out and also resets the first-launch setup.

Restrict logins to your organization

Tech leads who roll Claude Code out to a team should stop developers from logging in with personal accounts. Set both keys in the machine’s managed settings file (managed-settings.json, deployed through MDM):

{
  "forceLoginMethod": "claudeai",
  "forceLoginOrgUUID": "YOUR_ORG_UUID"
}

YOUR_ORG_UUID is shown in the claude.ai admin settings for your Teams or Enterprise organization. Know the gaps before you rely on it:

• Server-managed settings cannot redirect a first login, because they reach only accounts that already belong to your organization. Deploy these keys through device management, and if you also use server-managed settings, set them in both places.
• The interactive login screen pre-selects the method without enforcing it, and claude setup-token and /install-github-app enforce only forceLoginMethod, so they can still mint a token in another organization.
• Environment credentials are blocked at startup once forceLoginOrgUUID is set: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, and apiKeyHelper cannot prove organization membership. Cloud-provider sessions and Anthropic profile credentials are not blocked, so restrict cloud access with IAM and check profiles with /status.
• Console logins are not checked for organization: for a Console login, forceLoginOrgUUID only pre-selects the organization on the sign-in page, and a developer who logged in to the Console before you deployed the keys stays logged in. Because the login screen does not enforce forceLoginMethod either, control who can bill through the Console by managing membership of your Console organization.

The full rollout, including permissions and telemetry, is on managed policy for coding agents and enterprise integration.

How do you prove the login is correct?

Do not ask the model which account it is using: the model sees the conversation, not your credential store. Check the harness instead, and make each check a gate someone owns.

• Developer, once per machine: claude auth status --text prints a Login method line plus the base URL and any proxy; /status in a session shows the login method, organization, and email, and marks any credential that is configured but unused.
• CI, every run: the smoke step above fails the job before real work starts if the secret is missing, expired, or revoked.
• Tech lead, once per rollout: on one managed laptop, log in with a personal account and confirm Claude Code refuses it; then export a test ANTHROPIC_API_KEY and confirm startup is blocked.
• Whoever owns the budget, weekly: compare /usage (subscriptions) or the Console usage page (API billing) with what you expected; a surprise Console bill from a subscription user is the precedence trap above.

When Claude Code authentication fails

The browser does not open, or never returns to the terminal. Press c to copy the URL, sign in anywhere, and paste the code at Paste code here if prompted. This is normal over SSH, in WSL2, and in containers.

Login expired · Please run /login. Run /login. From v2.1.217, Claude Code warns three days before expiry with Your login expires in 3 days · run /login to renew (v2.1.203–v2.1.216 warned five days out). The warning appears only when a claude.ai or Console login is the active credential. Renew before you start background sessions or Remote Control: an unattended session stops making progress once its login expires.

You pay for a subscription but see API charges, or requests fail after a key was revoked. An environment key is outranking your login. Run unset ANTHROPIC_API_KEY, remove it from your shell profile, and confirm with /status.

Your apiKeyHelper script is failing. Run the script by hand with stdout piped to wc -c. It must print only the key, exit 0, and finish in well under 10 seconds; Claude Code shows a slow-helper notice after 10.

Startup exits with an organization policy error. Your admin set forceLoginOrgUUID, which blocks environment keys. Unset them and use /login with your company account.

Cloud credentials expired mid-day. Re-run aws sso login or gcloud auth application-default login. To make it automatic, set awsAuthRefresh for Bedrock or gcpAuthRefresh for Google Cloud’s Agent Platform in your settings.

The model is not available on your provider. Enable it in the Bedrock model catalog or Model Garden, or pin a model your account can invoke; the models hub lists the IDs. For Foundry, first check that ANTHROPIC_FOUNDRY_RESOURCE is your real resource name, not the placeholder.

A macOS Console login fails over SSH. A Console login that creates an API key needs a writable Keychain. Unlock the Keychain, or choose the keyless Console sign-in.

You hit a usage limit on Pro or Max. Run /usage to see which window was reached and when it resets, then reduce parallel sessions or move to a larger plan. Claude Code cost control covers the trade-offs.

Where to go next after logging in to Claude Code

Authentication follows installing Claude Code. Next, set the permission mode, model, and settings hierarchy for your projects. Running Codex too? See Codex authentication.

Configure Claude Code Permission modes, model selection, and the settings hierarchy.

Claude Code in CI/CD Run Claude Code in pipelines with scoped secrets.

LLM gateway configuration Route Claude Code through your own proxy or gateway.

Agent identity and secrets Scope, store, and rotate the credentials agents use.