The official Claude SDKs are configured almost entirely through environment variables, which is what makes them easy to deploy — and occasionally maddening to debug, because several variables can compete to supply the same setting. This article catalogs the variables documented for the first-party Claude API SDKs and the Claude Platform on AWS client, then spells out the precedence rules.
The variables
| Variable | What it does |
|---|---|
ANTHROPIC_API_KEY | Static API key; picked up automatically by every official SDK |
ANTHROPIC_AUTH_TOKEN | Bearer token (e.g. an OAuth access token handed off from ant auth print-credentials --env) |
ANTHROPIC_PROFILE | Selects a named on-disk profile; a missing profile is an error, not a fall-through |
ANTHROPIC_CONFIG_DIR | Overrides the profile directory (default ~/.config/anthropic on Linux/macOS, %APPDATA%\Anthropic on Windows) |
ANTHROPIC_BASE_URL | Overrides the API host (see the base URL article) |
ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_IDENTITY_TOKEN / ANTHROPIC_IDENTITY_TOKEN_FILE | The Workload Identity Federation set — all needed together for keyless auth |
ANTHROPIC_WORKSPACE_ID | Scopes a WIF-minted token to one workspace; required when the federation rule spans several |
ANTHROPIC_AWS_WORKSPACE_ID | Claude Platform on AWS only: the wrkspc_... workspace ID (distinct from ANTHROPIC_WORKSPACE_ID) |
ANTHROPIC_AWS_API_KEY | Claude Platform on AWS only: platform API key sent as x-api-key |
AWS_REGION / AWS_DEFAULT_REGION | Claude Platform on AWS only: selects the regional endpoint; no default — the client errors without it |
The AnthropicAWS client additionally honors the whole standard AWS credential chain (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_WEB_IDENTITY_TOKEN_FILE + AWS_ROLE_ARN, and so on) for SigV4 signing. Java also accepts the anthropic.apiKey system property as an alternative to the env var.
Precedence: first match wins
For the first-party SDKs, credential resolution follows a documented order:
1. A constructor argument (api_key=, auth_token=, or credentials=) — code always beats environment. 2. ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN — either shadows federation entirely. 3. ANTHROPIC_PROFILE, selecting a named profile. 4. The federation env vars. 5. The active on-disk profile from <config_dir>/active_config, falling back to a profile literally named default. The ant CLI resolves in the same order as the SDKs, with explicit command-line flags at the very top; Claude Code and the Claude Agent SDK honor the same resolution too, so one mental model covers the whole toolchain.
ANTHROPIC_API_KEY="" selects the API-key path with an empty key — it does not fall through to your profile or WIF setup. Unset unused variables; never blank them.How profiles and env vars mix
Profiles are JSON files (configs/<profile>.json for settings such as base_url, organization_id, and workspace_id; credentials/<profile>.json for cached tokens, written with file mode 0600). One subtle documented rule: when a profile is loaded, environment variables fill only the fields the profile omits — they never override fields the profile sets explicitly. If a profile pins a base_url, exporting ANTHROPIC_BASE_URL will not budge it; edit the profile or use a different one.
Debugging which variable won
When behavior doesn't match expectations, resist guessing. On machines with the ant CLI installed, ant auth status reports exactly which credential source and profile won the resolution — usually revealing a forgotten export in a shell profile. In application code, the fastest check is to print the relevant variables at startup (never the secret values themselves — just which ones are set) and compare against the precedence list above.
Two hygiene habits prevent most of these incidents in the first place. Keep credential variables out of shared shell startup files on multi-project machines — a key exported in ~/.zshrc for one project silently authenticates every other project on the box, and shadows their profiles too. And in deployment manifests, set only the variables an environment actually uses: a container that authenticates with Workload Identity Federation should not also carry an ANTHROPIC_API_KEY, because the key would win the precedence race and quietly defeat the keyless setup.
Where to go next
For the auth methods behind these variables, see API key patterns and Workload Identity Federation. For structuring dev/staging/prod configuration on top of profiles, continue to Configuring the SDK for Dev, Staging, and Production.