126 lines
5.6 KiB
Markdown
126 lines
5.6 KiB
Markdown
# 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.
|