The AnthropicAWS client (and its TypeScript, Java, Go, C#, Ruby, and PHP siblings) is configured almost entirely through the environment: two platform-specific variables that identify where requests go, and the standard AWS credential variables that determine who is making them. This page is the single-table reference, followed by the precedence rules that decide which credential source wins when several are present.
The reference table
| Variable | What it does | Required? |
|---|---|---|
ANTHROPIC_AWS_WORKSPACE_ID | The wrkspc_... workspace ID sent on every request (as the anthropic-workspace-id header). Scopes usage, quota, cost, files, and batches to that workspace. | Yes — no default; client errors at construction without it (or a workspace_id constructor arg) |
AWS_REGION | Selects the endpoint (https://aws-external-anthropic.{region}.api.aws) and the SigV4 signing region. Must be the workspace's bound region. | Yes — no default; falls back to AWS_DEFAULT_REGION, then errors |
AWS_DEFAULT_REGION | Fallback read when AWS_REGION is unset. | No |
ANTHROPIC_AWS_API_KEY | An API key generated in the AWS Console (Claude Platform on AWS → API keys), sent as x-api-key instead of SigV4 signing. Requires the CallWithBearerToken IAM action. | No — alternative to SigV4 |
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY | Static AWS credentials, first stop in the AWS default credential provider chain, used for SigV4 signing. | No — one credential source among several |
AWS_SESSION_TOKEN | Session token accompanying temporary credentials (assumed roles, SSO, STS). The SDK adds the required x-amz-security-token header automatically. | Only with temporary credentials |
AWS_PROFILE | Selects a named profile from your shared AWS config/credentials files (including SSO and credential_process profiles) when the chain reads them. | No |
AWS_WEB_IDENTITY_TOKEN_FILE + AWS_ROLE_ARN | Web identity federation — how EKS IRSA and GitHub Actions supply role credentials without static keys. | No — set by those platforms |
One near-miss to know about: ANTHROPIC_WORKSPACE_ID (without _AWS_) is a different variable belonging to the first-party API's workload identity federation setup. Setting it does nothing for Claude Platform on AWS, and it is a classic source of "the variable is definitely set" confusion.
What the SDK reads first
When more than one credential source is present, the client resolves them in a fixed order — first match wins:
| Priority | Source | Auth mode |
|---|---|---|
| 1 | apiKey constructor argument | x-api-key header |
| 2 | awsAccessKey + awsSecretAccessKey constructor arguments | SigV4 |
| 3 | awsProfile constructor argument | SigV4, named profile |
| 4 | ANTHROPIC_AWS_API_KEY environment variable | x-api-key header |
| 5 | AWS default credential provider chain (env vars → shared files/SSO → web identity → ECS → EC2 IMDS) | SigV4 |
Two rules fall out of this. Constructor arguments always beat environment variables — useful in tests, dangerous when a forgotten hard-coded key shadows the environment. And an API key anywhere in slots 1 or 4 switches the client away from SigV4 entirely, so if requests are unexpectedly failing IAM checks for CallWithBearerToken, look for a stray ANTHROPIC_AWS_API_KEY in the environment.
AWS_REGION and the workspace's endpoint; 403s are identity (wrong workspace ID or missing IAM action); and "Outbound web identity federation is disabled for your account" is the one-time account prerequisite — aws iam enable-outbound-web-identity-federation — not an environment variable problem at all.Setting a sane baseline
For most deployments the minimal, least-surprising environment is: ANTHROPIC_AWS_WORKSPACE_ID and AWS_REGION set explicitly, no static AWS keys, and credentials arriving through the platform's native mechanism — instance roles on EC2, task roles on ECS, IRSA on EKS. That keeps slot 5 as the only active credential source, which is exactly what you want: one path, no shadowing. Reserve ANTHROPIC_AWS_API_KEY for processes that genuinely cannot sign requests, and prefer short-term generated tokens for those (see short-term credentials).
Where to go next
See the credential chain in depth, Python SDK setup for a verified first request, and EKS IRSA or EC2 instance roles for keyless production patterns.