AWS Authentication

Relevant source files

The following files were used as context for generating this wiki page:

• internal/awsauth/awsauth.go
• aws/aws.go
• aws/aws_test.go
• aws/aws_live_test.go
• bedrock/bedrock_test.go

AWS Authentication in the Anthropic Go SDK provides a mechanism for authenticating requests to Anthropic services hosted on AWS infrastructure. This system supports multiple authentication modes, including standard Anthropic API keys (via x-api-key headers) and AWS Signature Version 4 (SigV4) signing for enhanced security and integration with AWS Identity and Access Management (IAM).

The module is designed to be flexible, allowing developers to provide credentials explicitly through configuration structures or rely on the standard AWS credential provider chain, which includes environment variables, shared credentials files, and IAM roles.

Sources: aws/aws.go:37-65, internal/awsauth/awsauth.go:21-32

Authentication Architecture

The authentication system is built around a resolution logic that determines whether to use API keys or AWS SigV4 signing based on the provided configuration and environment variables.

Resolution Logic

The SDK follows a specific order of precedence to resolve authentication parameters:

1. API Key Mode: Triggered if an APIKey is explicitly provided in the configuration or if the ANTHROPIC_AWS_API_KEY environment variable is set.
2. SigV4 Mode: Triggered if AWS-specific credentials (Access Key and Secret Key) are provided, an AWS Profile is specified, or if neither API keys nor explicit AWS keys are found (falling back to the default AWS credential chain).

Sources: aws/aws.go:73-81, internal/awsauth/awsauth.go:104-123

Flow Diagram: Authentication Resolution

The following diagram illustrates how the SDK decides which authentication method to apply during client initialization.

Explanation: The system prioritizes explicit API keys, then explicit AWS credentials, then environment-based API keys, finally defaulting to AWS SigV4 via the credential chain.
Sources: internal/awsauth/awsauth.go:104-123

Configuration and Parameters

Authentication behavior is controlled by the ClientConfig and ResolveParams structures.

Client Configuration

The ClientConfig struct holds the primary inputs for authentication.

Field	Type	Description
APIKey	string	Anthropic API key; takes precedence over AWS credentials.
AWSAccessKey	string	AWS access key ID for SigV4.
AWSSecretAccessKey	string	AWS secret access key for SigV4.
AWSProfile	string	Named AWS profile for resolution via provider chain.
AWSRegion	string	AWS region used for URL derivation and SigV4 signing.
WorkspaceID	string	Required header (anthropic-workspace-id) for all requests.
SkipAuth	bool	Disables all authentication and workspace ID requirements.

Sources: aws/aws.go:37-65, internal/awsauth/awsauth.go:21-32

Environment Variables

The system automatically looks up various environment variables if fields are missing from the configuration:

• ANTHROPIC_AWS_API_KEY: Fallback for the API Key.
• ANTHROPIC_AWS_WORKSPACE_ID: Fallback for the Workspace ID.
• AWS_REGION or AWS_DEFAULT_REGION: Fallback for the AWS Region.
• ANTHROPIC_AWS_BASE_URL: Fallback for overriding the default service URL.

Sources: internal/awsauth/awsauth.go:76-102

SigV4 Signing Middleware

When SigV4 mode is active, the SDK utilizes an HTTP middleware to sign requests. This middleware intercepts the outgoing request, calculates a SHA-256 hash of the body, and applies the AWS Signature Version 4.

Key Implementation Details

• Body Handling: The middleware reads the request body into memory to calculate the signature hash. It then replaces r.Body with a bytes.Reader and populates r.GetBody to support request retries.
• Service Metadata: Signing requires a specific AWS Service Name (e.g., aws-external-anthropic) and the target AWS Region.
• Hash Calculation: A hex-encoded SHA-256 hash of the payload is included in the signing process.

Sources: internal/awsauth/awsauth.go:167-208, aws/aws.go:35

Sequence Diagram: SigV4 Signing Process

The sequence below shows how a request is signed before being dispatched to the AWS gateway.

Explanation: The middleware buffers the body to ensure the signature matches the transmitted content exactly and supports retries by resetting the body reader.
Sources: internal/awsauth/awsauth.go:167-208

AWS Credential Resolution

The SDK integrates with the standard AWS SDK for Go (v2) to resolve credentials. The BuildAWSConfig function handles this integration.

1. Static Credentials: If AWSAccessKey and AWSSecretAccessKey are provided in ClientConfig, they are used directly.
2. Profile-Based: If AWSProfile is provided, the SDK loads the configuration specifically for that profile.
3. Default Chain: If no explicit credentials or profile are provided, it calls config.LoadDefaultConfig, which checks environment variables, IAM roles, and the shared credentials file.

Eager verification is performed using awsCfg.Credentials.Retrieve(ctx) during setup to ensure credentials are valid before the first request is attempted.

Sources: internal/awsauth/awsauth.go:133-165

Integration with Services (Bedrock and Gateway)

The AWS authentication system is used by different transport layers within the SDK.

• AWS Gateway: Uses the service name aws-external-anthropic and typically derives its URL from the region (e.g., https://aws-external-anthropic.{region}.api.aws).
• Bedrock: While utilizing similar SigV4 logic, it may handle URL encoding for ARNs and colons differently within its own middleware to accommodate Bedrock-specific endpoint structures.

Sources: aws/aws.go:35-102, bedrock/bedrock_test.go:14-60

Summary

AWS Authentication in the Anthropic Go SDK provides a robust interface for interacting with AWS-hosted Anthropic services. By supporting both standard API keys and AWS SigV4, it caters to simple use cases and high-security enterprise environments alike. The reliance on the standard AWS SDK for Go ensures that developers can leverage existing AWS identity management patterns, such as IAM roles and credential profiles, without additional complexity.

Sources: aws/aws.go:8-32, internal/awsauth/awsauth.go:211-237