Anthropic AWS Platform SDK

Purpose and Scope

The @anthropic-ai/aws-sdk package is the TypeScript SDK entry point for Claude Platform on AWS, the Anthropic-operated platform experience that is accessed through AWS commercial and identity integration. It is different from the Amazon Bedrock package: Bedrock uses AWS-operated inference infrastructure and a Bedrock-specific API surface, while Claude Platform on AWS preserves Anthropic platform capabilities behind AWS authentication, access control, and marketplace billing. This page explains how this package is shaped, which client it exports, and how authentication and region configuration are expected to work in code.

Sources: packages/aws-sdk/package.json, packages/aws-sdk/src/index.ts, packages/aws-sdk/src/client.ts

The package is intentionally close to the main Anthropic TypeScript SDK. Its client class extends the generated Anthropic client from @anthropic-ai/sdk/client, so familiar resources such as messages.create remain the application-facing API. The AWS package specializes the transport and request preparation layer: it adds AWS region resolution, optional workspace headers, API-key authentication for the AWS platform gateway, SigV4 signing, and a provider-chain escape hatch for environments where the Node AWS credential chain is not available.

Sources: packages/aws-sdk/src/client.ts, packages/aws-sdk/src/core/auth.ts

Relevant Source Files

• packages/aws-sdk/package.json defines the published package name, package metadata, build/test scripts, CommonJS and ESM exports, and dependencies on the main SDK plus Smithy/AWS signing libraries.
• packages/aws-sdk/src/index.ts is the public package entrypoint. It re-exports the client module, exports AnthropicAws as the default export, and exposes the AwsClientOptions type.
• packages/aws-sdk/src/client.ts defines AwsClientOptions, the AnthropicAws class, AWS-specific option fields, region/base URL behavior, and integration with request authentication middleware.
• packages/aws-sdk/src/core/auth.ts implements SigV4 header generation through Smithy SignatureV4, default AWS credential provider-chain loading, explicit credential handling, and connection-error wrapping for credential resolution failures.
• packages/aws-sdk/tests/client.test.ts verifies client initialization, region and base URL behavior, environment cleanup assumptions, workspace and credential options, and request-time auth integration using a mocked getAuthHeaders.
• packages/aws-sdk/tests/auth.test.ts verifies the low-level signer input, including method, path, query parameters, host header, removal of connection, and request body propagation.

Package Entry Points and Installation

Install the AWS platform SDK as its own npm package rather than importing it from the main SDK package. The package metadata identifies it as @anthropic-ai/aws-sdk, versioned independently from the root @anthropic-ai/sdk package, with dist/index.js and dist/index.d.ts as the primary CommonJS build artifacts. Its exports map also supports default ESM output and subpath access to built files, which makes it usable from both require and modern import consumers after the package is built and published.

Sources: packages/aws-sdk/package.json

npm install @anthropic-ai/aws-sdk

import AnthropicAws from '@anthropic-ai/aws-sdk';
 
const client = new AnthropicAws({
  apiKey: process.env.ANTHROPIC_AWS_API_KEY,
  awsRegion: 'us-west-2',
  workspaceId: 'ws-test',
});
 
const message = await client.messages.create({
  model: 'claude-opus-4-8',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello from Claude Platform on AWS' }],
});

The public entrypoint is intentionally small. packages/aws-sdk/src/index.ts exports everything from ./client, makes AnthropicAws the default export, and re-exports the AwsClientOptions type. A comment in that file also notes that auth internals are shared via symlink rather than package exports, which is a useful boundary for consumers: application code should configure the client, not import signing helpers as stable public API.

Sources: packages/aws-sdk/src/index.ts

Client Configuration Reference

AwsClientOptions extends the main SDK ClientOptions, then adds AWS-specific fields. awsRegion selects the AWS API gateway region. The documented precedence is constructor argument, AWS_REGION, AWS_DEFAULT_REGION, then the region in the AWS shared config file for the selected awsProfile or default profile. The comment also calls out an asynchronous edge case: if region resolution falls through to the shared config file, the region and derived baseURL may be undefined until await client.ready or until the first request completes initialization.

Sources: packages/aws-sdk/src/client.ts

The default base URL is derived from region as https://aws-external-anthropic.<region>.api.aws, and the client tests assert this shape for both API-key and explicit SigV4 credential initialization. The same tests assert that a caller-provided baseURL is preserved, which is important for private gateways, test doubles, or organization-specific routing. If neither a region nor a base URL can be resolved, client.ts constructs an AnthropicError explaining the accepted fixes: pass awsRegion, set AWS_REGION or AWS_DEFAULT_REGION, configure region in ~/.aws/config, or provide baseURL or ANTHROPIC_AWS_BASE_URL.

Sources: packages/aws-sdk/src/client.ts, packages/aws-sdk/tests/client.test.ts

Authentication Behavior

Authentication supports two main paths. If apiKey is provided, the client treats it as the preferred credential for AWS platform gateway access; the option comment says it takes precedence over AWS credential options and can also come from ANTHROPIC_AWS_API_KEY. If API-key authentication is not used, the SDK prepares SigV4 headers. That SigV4 path can use explicit awsAccessKey and awsSecretAccessKey, optionally with awsSessionToken, or it can resolve credentials through the AWS provider chain for the configured profile.

Sources: packages/aws-sdk/src/client.ts, packages/aws-sdk/src/core/auth.ts

The low-level getAuthHeaders helper accepts an AuthProps object with the request URL, region name, service name, AWS credential fields, optional profile, fetch options, custom provider-chain resolver, and logger. When explicit keys are present, it builds the credential object directly. Otherwise, it dynamically imports @aws-sdk/credential-providers and calls fromNodeProviderChain, passing the profile and a Smithy FetchHttpHandler. The dynamic import failure message tells users to pass new AnthropicAws({ providerChainResolver }) when their runtime cannot access that package.

Sources: packages/aws-sdk/src/core/auth.ts

Credential provider failures are wrapped as APIConnectionError rather than ordinary middleware errors. The source comment explains why: provider resolution may involve network-bound systems such as IMDS, SSO, or STS, so failures should remain within the SDK connection-error retry policy. After credentials are available, getAuthHeaders constructs a Smithy SignatureV4 signer using the configured service, region, credentials, and SHA-256 implementation, then signs an HttpRequest built from the outgoing method, URL path, query string, headers, and body.

Sources: packages/aws-sdk/src/core/auth.ts

Request Signing Details and Testing Signals

The auth tests are a compact specification for what gets signed. They verify that a POST request to /v1/messages keeps the path, converts URL search parameters into the Smithy query object, sets host from the request URL, and passes the body through to the signer. They also verify a subtle proxy-safe behavior: the SDK removes the connection header before signing because an intermediary may strip it, which would make a signature over that header fragile at the receiver.

Sources: packages/aws-sdk/tests/auth.test.ts, packages/aws-sdk/src/core/auth.ts

Client tests add higher-level confidence that the SDK can be configured in the ways users actually deploy it. The test setup clears AWS_REGION, AWS_DEFAULT_REGION, ANTHROPIC_API_KEY, ANTHROPIC_AWS_BASE_URL, ANTHROPIC_AWS_API_KEY, and ANTHROPIC_AWS_WORKSPACE_ID before each case so precedence is tested deliberately rather than accidentally inherited from the local environment. The request helper calls client.messages.create, which confirms that the AWS client preserves the standard Messages resource shape while changing the authentication and routing behavior underneath.

Sources: packages/aws-sdk/tests/client.test.ts

Choosing This Package

Use @anthropic-ai/aws-sdk when you want Claude Platform on AWS rather than the direct Anthropic API package or the Amazon Bedrock package. In practical terms, that means your application still uses Anthropic-style SDK resources, but deployment teams can use AWS identity, IAM control patterns, and marketplace billing arrangements for platform access. For teams already using the main SDK, migration is mostly about changing the client import and deciding whether requests should authenticate with an AWS platform API key, explicit SigV4 credentials, the default AWS credential chain, or an organization-managed proxy with skipAuth.

Sources: packages/aws-sdk/src/index.ts, packages/aws-sdk/src/client.ts, packages/aws-sdk/package.json

Next, read the core Messages API pages if you need request and response examples, the Amazon Bedrock SDK page if you are comparing AWS-operated Bedrock with Claude Platform on AWS, and the authentication/client configuration pages if you need broader guidance on environment variables, custom base URLs, middleware, retries, and runtime constraints.