AWS Bedrock

Purpose and Scope

The OpenAI Node SDK supports Amazon Bedrock through a provider integration that routes the normal SDK resource model to Bedrock's OpenAI-compatible API. In practice, this means application code can continue using familiar surfaces such as client.responses.create() and client.models.list(), while authentication, endpoint selection, and request signing are handled by the Bedrock provider. The main reader task for this page is deciding which Bedrock entrypoint to use, how credentials are selected, and what behavior the repository tests guarantee before you run code against AWS-managed infrastructure.

Sources: bedrock.md, tests/lib/bedrock-provider.test.ts

Amazon Bedrock availability is not identical to direct OpenAI API availability. The repository guide explicitly tells callers to choose a model that supports the Responses API, because a model returned by Bedrock's Models API may support a different Bedrock inference API instead. Treat Bedrock as a deployment path with AWS-controlled regional availability, endpoint support, feature support, and error behavior. Unsupported calls are not translated into a separate SDK abstraction; they surface as the provider's normal HTTP errors through the same OpenAI client request and error machinery.

Sources: bedrock.md, tests/live/bedrock.live.test.ts

Relevant Source Files

• bedrock.md — user-facing setup guide for the Bedrock provider, including imports, endpoint derivation, authentication precedence, dependency expectations, and examples for bearer and SigV4 modes.
• tests/lib/bedrock.test.ts — unit coverage for the BedrockOpenAI client shape, base URL normalization, region precedence, environment fallback, request behavior, streaming, and typed Bedrock client options.
• tests/lib/bedrock-provider.test.ts — provider-level coverage for dependency-free bearer mode, AWS SigV4 mode, environment refresh behavior, fallback suppression with null, and direct request headers.
• tests/live/bedrock.live.test.ts — guarded live test harness for real AWS Bedrock calls across bearer, environment bearer, default AWS credential chain, profile, static credentials, and custom provider modes.

Provider Entry Points and Endpoint Selection

The primary documented pattern is to construct the standard OpenAI client with a Bedrock provider. For bearer-token-only use, import bedrock from openai/providers/bedrock; for AWS credential and SigV4 use, import bedrock from openai/providers/bedrock/aws. Both patterns preserve the normal SDK resources, so a Responses API request still looks like client.responses.create({ model, input }). The provider owns the Mantle endpoint and sets the client's base URL to the regional Bedrock OpenAI-compatible route rather than the default OpenAI API route.

Sources: bedrock.md, tests/lib/bedrock-provider.test.ts

import OpenAI from 'openai';
import { bedrock } from 'openai/providers/bedrock/aws';
 
const client = new OpenAI({
  provider: bedrock({ region: 'us-west-2' }),
});
 
const response = await client.responses.create({
  model: 'openai.gpt-5.4',
  input: 'Say hello!',
});
 
console.log(response.output_text);

Endpoint derivation follows a small but important precedence model. A supplied region resolves to https://bedrock-mantle.<region>.api.aws/openai/v1. The region may come from the explicit provider or client options, then from AWS_REGION, then from AWS_DEFAULT_REGION. A supplied baseURL or AWS_BEDROCK_BASE_URL overrides the derived endpoint, and the tests also verify normalization when a URL is supplied with a trailing /responses segment. This keeps application code portable between the default Bedrock Mantle route and private or test endpoints without changing resource calls.

Sources: bedrock.md, tests/lib/bedrock.test.ts, tests/lib/bedrock-provider.test.ts

Authentication Modes and Dependency Expectations

Authentication is intentionally split into bearer and AWS credential modes. The dependency-free provider entrypoint supports Bedrock API keys through apiKey, a refreshable tokenProvider, or the AWS_BEARER_TOKEN_BEDROCK environment variable. The provider test suite verifies that bearer mode sends an Authorization: Bearer ... header to the Mantle endpoint, that an environment bearer token is refreshed across withOptions(), and that setting apiKey: null skips environment bearer fallback instead of silently using an unwanted token. Use this entrypoint when your deployment already has a Bedrock bearer token and does not need AWS request signing.

Sources: bedrock.md, tests/lib/bedrock-provider.test.ts

import OpenAI from 'openai';
import { bedrock } from 'openai/providers/bedrock';
 
const client = new OpenAI({
  provider: bedrock({
    region: 'us-west-2',
    apiKey: process.env['AWS_BEARER_TOKEN_BEDROCK'],
  }),
});

SigV4 authentication requires the AWS-specific provider entrypoint and its peer dependencies: @aws-sdk/credential-provider-node, @smithy/hash-node, and @smithy/signature-v4. The guide states that this entrypoint uses normal static imports, so bundlers and serverless packagers can include the dependencies, and a missing dependency fails immediately with the runtime's normal module-not-found error. The tests import SignatureV4 and exercise AWS credential paths, while the dependency-free entrypoint deliberately points AWS credential users to openai/providers/bedrock/aws rather than attempting to sign without the required packages.

Sources: bedrock.md, tests/lib/bedrock-provider.test.ts

npm install @aws-sdk/credential-provider-node @smithy/hash-node @smithy/signature-v4

import OpenAI from 'openai';
import { bedrock } from 'openai/providers/bedrock/aws';
 
const client = new OpenAI({
  provider: bedrock({
    region: 'us-west-2',
    apiKey: null,
    profile: 'my-profile',
  }),
});

SigV4 Behavior and Credential Selection

When using the AWS entrypoint, explicit bearer and AWS credential modes are mutually exclusive, and only one AWS credential mode should be configured at a time. The guide lists the selection order as one explicit mode passed to bedrock(...), then AWS_BEARER_TOKEN_BEDROCK, then the default AWS credential chain. AWS credential modes include static credentials with accessKeyId, secretAccessKey, and optional sessionToken; a shared configuration profile; or a custom credentialProvider. Passing apiKey: null is significant because it disables bearer fallback and forces AWS credentials, which the tests validate by expecting a credentials error when metadata is disabled and no credentials are available.

Sources: bedrock.md, tests/lib/bedrock-provider.test.ts, tests/live/bedrock.live.test.ts

const client = new OpenAI({
  provider: bedrock({
    region: 'us-west-2',
    apiKey: null,
    accessKeyId: process.env['AWS_ACCESS_KEY_ID'],
    secretAccessKey: process.env['AWS_SECRET_ACCESS_KEY'],
    sessionToken: process.env['AWS_SESSION_TOKEN'],
  }),
});

It is also useful to distinguish this Bedrock SigV4 path from OpenAI workload identity federation. The Bedrock provider signs requests to AWS-managed Bedrock infrastructure when AWS credential mode is selected. By contrast, OpenAI workload identity federation documentation treats AWS-issued OIDC tokens as subject tokens for exchanging into OpenAI access tokens and does not use SigV4-signed requests as the federation subject token. In code reviews, keep those two concerns separate: Bedrock SigV4 is transport authentication for the Bedrock provider, while workload identity federation is an OpenAI authentication flow for direct OpenAI access tokens.

Sources: bedrock.md, tests/lib/bedrock-provider.test.ts

API Components Reference

The tested behavior around null options is worth preserving in production configuration. apiKey: null prevents the provider from falling back to AWS_BEARER_TOKEN_BEDROCK, and baseURL: null prevents fallback to AWS_BEDROCK_BASE_URL. Those options are useful when a service must fail closed instead of accidentally using environment state inherited from a shell, container image, or CI job. This is especially important in multi-cloud or shared developer environments where AWS variables may be present for unrelated tooling.

Sources: tests/lib/bedrock-provider.test.ts, tests/lib/bedrock.test.ts

Live Testing Signals

The live test is intentionally guarded so it cannot make AWS requests by accident. It throws unless BEDROCK_LIVE_TEST=1 is set and expects the pnpm test:live:bedrock script to run the specific live test file. It also requires a Bedrock model through BEDROCK_MODEL, validates the requested authentication mode through BEDROCK_LIVE_AUTH, reads the region from AWS_REGION or AWS_DEFAULT_REGION, and optionally reads AWS_BEDROCK_BASE_URL. The configured client disables retries and uses a long timeout, then lists models and creates a Responses API response with store: false.

Sources: tests/live/bedrock.live.test.ts

BEDROCK_LIVE_TEST=1 BEDROCK_LIVE_AUTH=profile AWS_PROFILE=my-profile \
AWS_REGION=us-west-2 BEDROCK_MODEL=openai.gpt-oss-120b pnpm test:live:bedrock

Supported live authentication modes are bearer, environment-bearer, default-chain, profile, static, and custom-provider. The optional streaming path is enabled with BEDROCK_LIVE_STREAM=1, which adds a second streaming inference request. That matrix gives maintainers confidence that the same provider contract works with direct Bedrock API keys, environment-provided bearer tokens, the AWS default credential chain, shared config profiles, temporary static credentials, and a caller-supplied AWS credential provider. Before enabling the live test in CI, confirm the model supports Responses API compatibility in the selected AWS Region.

Sources: tests/live/bedrock.live.test.ts

Next Steps

For application code, start with the dependency-free Bedrock provider if you have an Amazon Bedrock API key and do not need SigV4. Choose the AWS provider entrypoint when your runtime should use IAM, profiles, temporary credentials, or a custom AWS credential provider. After selecting authentication, verify the region and model pair against Bedrock's Responses-compatible model availability, then run a minimal models.list() and responses.create() flow before adding streaming or tool workflows. If you are also evaluating direct OpenAI authentication from AWS workloads, review workload identity federation separately so SigV4 signing and OIDC token exchange do not get conflated.

Sources: bedrock.md, tests/live/bedrock.live.test.ts