# 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`).
  ```bash
  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**:
  ```json
  { "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.