The AnthropicAWS client authenticates most requests with SigV4 — AWS's request-signing scheme — which means it needs AWS credentials from somewhere. Rather than making you wire them in by hand, the SDK resolves them through a defined precedence: first its own client-level settings, then the standard AWS default credential provider chain. When authentication misbehaves, the fix is nearly always "identify which link in the chain actually won."
Layer 1: client-level precedence
Before touching the AWS chain, the client checks its own configuration, in this order — first match wins:
| Priority | Source | Resulting auth |
|---|---|---|
| 1 | api_key constructor argument | API key (x-api-key header) |
| 2 | aws_access_key + aws_secret_access_key constructor arguments | SigV4 |
| 3 | aws_profile constructor argument | SigV4 with that named profile |
| 4 | ANTHROPIC_AWS_API_KEY environment variable | API key (x-api-key header) |
| 5 | AWS default credential provider chain | SigV4 |
Two notes. First, an explicit constructor argument beats everything — including an API-key environment variable — so code that hardcodes credentials will silently ignore your carefully configured roles. Second, API keys here are Claude Platform on AWS keys generated in the AWS Console (Claude Platform on AWS → API keys); first-party sk-ant-api... keys do not work with this endpoint, and API-key principals additionally need the aws-external-anthropic:CallWithBearerToken IAM action.
Layer 2: the AWS default credential provider chain
If nothing at the client level matched, the SDK falls through to the same chain every AWS SDK uses, checked in this order:
1. Environment variables. AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and (for temporary credentials) AWS_SESSION_TOKEN. Highest priority within the chain — and the classic source of surprises, because a leftover key pair exported in a shell or baked into a container image will shadow every role-based mechanism below.
2. Shared credentials and config files. The ~/.aws/credentials and ~/.aws/config files, including profiles backed by IAM Identity Center (SSO) sign-in and credential_process helpers. This is the usual path on developer laptops.
3. Web identity. A token file plus role, via AWS_WEB_IDENTITY_TOKEN_FILE and AWS_ROLE_ARN — the mechanism behind Kubernetes IRSA and GitHub Actions OIDC federation.
4. ECS container credentials. The task role delivered through the container credentials endpoint in ECS and Fargate.
5. EC2 instance metadata (IMDS). The instance-profile role, fetched from the instance metadata service. Last in line, so it only applies when nothing above is present.
Diagnosing chain problems
The failure mode tells you where to look:
Error at client construction. The client raises before any request is sent if it cannot resolve the AWS region (AWS_REGION, falling back to AWS_DEFAULT_REGION — unlike the Bedrock client, there is no us-east-1 default) or the workspace ID (ANTHROPIC_AWS_WORKSPACE_ID). This is configuration, not credentials.
Signature rejection. Credentials were found but the signature didn't validate — commonly a region mismatch between the signing region and the endpoint. See SigV4 under the hood.
403. The request reached the server and authenticated, but authorization failed: typically a wrong workspace_id or a missing IAM action on the principal that won the chain. Verify which identity actually signed the request (for example with your AWS CLI's caller-identity check) before editing policies — the usual culprit is stray environment variables shadowing the role you think you're using.
In production, prefer the bottom of the chain: task roles, instance roles, and web identity give you short-lived, auto-rotated credentials with no secrets to manage. Reserve static keys and profiles for local development.
Where to go next
Role-based patterns get their own guides: EC2 instance roles, IRSA for Kubernetes, and workload identity federation for CI. For every environment variable the client reads, see the env var reference.