Direct answer
Treat the login method, credential header, base URL, and configuration persistence as separate concerns to avoid authentication conflicts and key leaks.
What this guide helps you solve
Help users choose the correct Claude Code authentication method and complete verifiable security configuration.
First distinguish the four authentication sources
Claude Code officially supports Claude subscription accounts, Anthropic Console API access, and enterprise cloud providers listed in the documentation. Organizations can also have the CLI use organization-signed credentials through the LLM gateway.
Billing, model visibility, and available interfaces differ across these methods. A third-party gateway API key is not a Claude subscription and does not automatically provide account features such as claude.ai on the web or Remote Control.
- Subscription account: Complete Claude account login through the browser.
- Console: Use API access billed to the associated account.
- Cloud providers: Configure identities and regions according to their respective official integrations.
- LLM gateway: Routes via base URL with organization-issued token/key.
Log in with your account and check status
Running claude for the first time starts browser authentication. To switch accounts later, run /login in an interactive session; use /logout to sign out of the saved account.
After authentication, run /status to check the current login method, model, and whether an Anthropic base URL is set. Successfully starting the CLI alone does not reveal where requests are routed.
claude/login
/statusWhen using an API Key, leave the key in an environment variable
ANTHROPIC_AUTH_TOKEN immediately takes precedence over a saved account. ANTHROPIC_API_KEY is used directly in -p non-interactive mode; when first detected in interactive mode, Claude Code asks whether to use it and remembers the choice. You can change that choice in /config.
Do not put real keys in the repository, tutorial screenshots, shell history, or a committed .claude/settings.json. Users must replace example placeholders only in their local environment.
export ANTHROPIC_API_KEY='<your-api-key>'
claude$env:ANTHROPIC_API_KEY = '<your-api-key>'
claudeGateway token and API key use different request headers
ANTHROPIC_AUTH_TOKEN is sent as Authorization: Bearer, while ANTHROPIC_API_KEY is sent as x-api-key. When a gateway returns 401, check both the credential and the request header expected by the server.
A gateway connection requires at least a base URL and credentials. Verify both in a temporary shell before deciding how to persist them, which keeps URL, authentication, and Claude Code issues separate during troubleshooting.
export ANTHROPIC_BASE_URL='https://gateway.example.com'
export ANTHROPIC_AUTH_TOKEN='<gateway-token>'
claudeexport ANTHROPIC_BASE_URL='https://gateway.example.com'
export ANTHROPIC_API_KEY='<gateway-api-key>'
claude
Persist configuration at the appropriate scope
~/.claude/settings.json is appropriate for global user settings. .claude/settings.local.json is appropriate for unshared, single-project settings and should be listed in gitignore. Shared .claude/settings.json files must not contain credentials.
Organizations that rotate tokens can use apiKeyHelper to read from a secret store instead of saving static plaintext in JSON. After configuration, use /status to confirm the credential source Claude Code actually uses.
{
"env": {
"ANTHROPIC_BASE_URL": "https://gateway.example.com",
"ANTHROPIC_AUTH_TOKEN": "<gateway-token>"
}
}Handle conflicts between existing logins and environment variables
ANTHROPIC_AUTH_TOKEN overrides a saved claude.ai login. Whether ANTHROPIC_API_KEY is used in interactive sessions depends on the initial choice or /config; it is always used in -p mode. Unset the variable to return to the saved account.
Troubleshoot in this order: check /status, confirm the base URL, confirm credential variables and request headers, send a minimal request, and only then check the model name. An unknown-model error usually means authentication and networking succeeded and the problem lies in model routing.
unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY
claudeOfficial sources and verification scope
This guide is based on public official documentation. Commands and configuration may change between client versions, so verify the linked sources before use.
Read the verification methodology