claude-code/docs/AUTH_GUIDE.md

Authentication Guide - Claude Code

This guide provides an overview of the various authentication methods supported by the Claude Code CLI, along with configuration steps and troubleshooting tips.

---

1st Party Anthropic Authentication

Claude Code primarily connects directly to the Anthropic API. There are three main ways to authenticate:

Direct API Key

The most common method for individual developers.

• Environment Variable: ANTHROPIC_API_KEY
• Setup: Export your key in your shell profile (e.g., .zshrc or .bashrc).

  export ANTHROPIC_API_KEY='sk-ant-api03-...'
  

• Security Note: This method is prioritized in CI and non-interactive environments.

Claude.ai OAuth (Subscriber Mode)

If you have a Claude Pro or Team subscription, you can log in using your Claude.ai account.

• Command: Run /login in the CLI.
• How it works: This opens a browser for OAuth authentication. Once completed, your session is managed via a local secure token.
• Internal Users: Internal Anthropic employees use a specialized version of this flow.

External Key Helpers

For teams using a secret manager (like 1Password CLI or AWS Secrets Manager), you can use a helper script.

• Setting: apiKeyHelper in your ~/.claude/settings.json.
• Example:

  { "apiKeyHelper": "op read 'op://private/Anthropic/api-key'" }
  

• Behavior: The CLI will execute this command to retrieve the key on startup.

---

Security & Workspace Trust

Claude Code implements a "Trust Dialog" to protect you from malicious repository settings.

Custom Scripts

Settings that execute arbitrary code (like apiKeyHelper, awsAuthRefresh, or awsCredentialExport) are subject to the following rules:

• Global Settings: Always trusted (stored in ~/.claude/settings.json).
• Project Settings: Only executed if you have explicitly "trusted" the workspace.
• Dialog: If a project-local script is detected, Claude Code will prompt you for approval before execution.

Warning

Never trust a workspace from an untrusted source, as it could use these helpers to exfiltrate your API keys or run malicious commands on your behalf.

---

3rd Party Cloud Providers

Claude Code supports using models hosted on major cloud platforms. To use these, you must enable the specific provider via environment variables.

AWS Bedrock

• Enable: Set CLAUDE_CODE_USE_BEDROCK=true.
• Authentication: Uses standard AWS SDK credentials (IAM Roles, ~/.aws/credentials, or AWS_ACCESS_KEY_ID).
• Region: Defaults to us-east-1. Override with AWS_REGION.
• Custom Auth: Supports awsAuthRefresh and awsCredentialExport settings for specialized SSO flows.

GCP Vertex AI

• Enable: Set CLAUDE_CODE_USE_VERTEX=true.
• Authentication: Uses Application Default Credentials (ADC) via google-auth-library.
• Configuration:
  • ANTHROPIC_VERTEX_PROJECT_ID: (Required) Your GCP project ID.
  • CLOUD_ML_REGION: (Optional) Your GCP region.
• Auth Refresh: Supports refreshGcpCredentialsIfNeeded logic for long-running sessions.

Azure Foundry

• Enable: Set CLAUDE_CODE_USE_FOUNDRY=true.
• Authentication:
  • Uses ANTHROPIC_FOUNDRY_API_KEY if provided.
  • Otherwise, falls back to DefaultAzureCredential (Azure AD).
• Endpoint: Configure via ANTHROPIC_FOUNDRY_RESOURCE or ANTHROPIC_FOUNDRY_BASE_URL.

---

Environment Variable Reference

Variable	Method	Description
ANTHROPIC_API_KEY	Direct	Your Anthropic API Key.
ANTHROPIC_AUTH_TOKEN	Direct	Use for bearer-token-based authentication.
ANTHROPIC_CUSTOM_HEADERS	All	A newline-separated list of Name: Value headers.
API_TIMEOUT_MS	All	Custom timeout for API requests (default: 600000ms).
CLAUDE_CODE_ADDITIONAL_PROTECTION	All	Sets x-anthropic-additional-protection: true.
CLAUDE_CODE_USE_BEDROCK	Bedrock	Enables the AWS Bedrock provider.
CLAUDE_CODE_USE_VERTEX	Vertex	Enables the GCP Vertex AI provider.
CLAUDE_CODE_USE_FOUNDRY	Foundry	Enables the Azure Foundry provider.
CLAUDE_CODE_SKIP_*_AUTH	3P	Bypasses local SDK auth for proxy/testing scenarios.

---

Advanced Configuration & Priority

When multiple authentication methods are available, Claude Code follows this priority:

1. Managed Context: CCR or Claude Desktop sessions always force OAuth to ensure session isolation. These sessions ignore local API keys and settings to prevent credential leakage.
2. Environment Variables: ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN (unless in "Homespace").
3. Key Helper: The apiKeyHelper script if defined in settings.
4. Local Store: Credentials saved from a prior /login or ~/.claude/settings.json.

Note

Using the --bare flag forces the CLI into a hermetic mode that only respects ANTHROPIC_API_KEY and explicitly passed settings, ignoring the local keychain and OAuth tokens.

---

Troubleshooting

Common Errors

• 401 Unauthorized: Typically indicates an expired API key or OAuth session.
• 403 Forbidden: Your account may not have access to the requested model or feature.
• AWS/GCP Auth Timeouts: Often caused by the metadata server check. Ensure your credentials are fresh or set the project/region variables explicitly.

Clearing Caches

If you encounter persistent auth issues, you can reset your local state:

1. Run /logout in a session.
2. Manually remove ~/.claude/config.json.
3. (macOS only) Clear relevant entries in the Keychain via Security.

---

Tip

Use claude --doctor to diagnose your current authentication state and connectivity.