Skip to content

bedrock.md

Latest commit

 

History

History
140 lines (105 loc) · 4.46 KB

bedrock.md

File metadata and controls

140 lines (105 loc) · 4.46 KB
Raw

OpenAI on Amazon Bedrock

The optional openai-java-bedrock artifact configures the standard OpenAI Java client for the OpenAI-compatible Amazon Bedrock Mantle endpoint. It uses the AWS SDK for Java 2.x credential chain and signs the final HTTP request with SigV4 on every attempt.

Installation

Use this artifact instead of adding AWS dependencies to the base OpenAI package yourself.

implementation("com.openai:openai-java-bedrock:4.45.0")
<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java-bedrock</artifactId>
  <version>4.45.0</version>
</dependency>

Standard AWS credentials

Configure AWS credentials as you normally would, then provide the region:

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.BedrockOpenAIOkHttpClient;

OpenAIClient client = BedrockOpenAIOkHttpClient.builder()
        .awsRegion("us-east-1")
        .build();

The default AWS chain supports system properties, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, ~/.aws/credentials, ~/.aws/config, AWS_PROFILE, IAM Identity Center (SSO), assume-role and web-identity profiles, container credentials, and instance-profile credentials. The SDK resolves fresh credentials and signs again before every retry.

Region resolution follows this order:

  1. awsRegion(...)
  2. AWS_REGION
  3. AWS_DEFAULT_REGION
  4. the AWS SDK's default region provider chain

Base URL resolution follows this order:

  1. baseUrl(...)
  2. AWS_BEDROCK_BASE_URL
  3. https://bedrock-mantle.{region}.api.aws/openai/v1

The bedrock-mantle SigV4 service name is intentional. Bedrock's OpenAI-compatible route is model-dependent: models such as openai.gpt-5.5 use /openai/v1, while openai.gpt-oss-120b uses /v1. The builder defaults to /openai/v1; configure the model's documented route explicitly when it differs:

OpenAIClient client = BedrockOpenAIOkHttpClient.builder()
        .awsRegion("us-east-1")
        .baseUrl("https://bedrock-mantle.us-east-1.api.aws/v1")
        .build();

Named profile

OpenAIClient client = BedrockOpenAIOkHttpClient.builder()
        .awsRegion("us-east-1")
        .awsProfile("production")
        .build();

Explicit temporary credentials

Prefer profiles and workload roles in production. Explicit credentials are useful for tests and short-lived credentials obtained elsewhere:

OpenAIClient client = BedrockOpenAIOkHttpClient.builder()
        .awsRegion("us-east-1")
        .awsAccessKeyId(accessKeyId)
        .awsSecretAccessKey(secretAccessKey)
        .awsSessionToken(sessionToken)
        .build();

For refreshable credentials, pass an AWS SDK AwsCredentialsProvider:

OpenAIClient client = BedrockOpenAIOkHttpClient.builder()
        .awsRegion("us-east-1")
        .awsCredentialsProvider(credentialsProvider)
        .build();

Bearer-token compatibility

AWS_BEARER_TOKEN_BEDROCK remains supported for compatibility and takes precedence over the default AWS chain. An explicit AWS credential mode takes precedence over that environment variable. You can also provide a bearer credential directly:

OpenAIClient client = BedrockOpenAIOkHttpClient.builder()
        .awsRegion("us-east-1")
        .apiKey(bedrockBearerToken)
        .build();

Explicit bearer and AWS credential modes are mutually exclusive.

Async and streaming responses

The same client configuration supports asynchronous and streaming calls:

OpenAIClientAsync client = BedrockOpenAIOkHttpClient.builder()
        .awsRegion("us-east-1")
        .build()
        .async();

Response streaming is supported. SigV4 request bodies must be replayable so the SDK can hash them and safely retry; one-shot streaming request bodies are rejected before network I/O. Asynchronous bearer-token and SigV4 authentication work runs on a dedicated client-owned executor by default; pass authenticationExecutor(...) to use a caller-owned executor instead.

Security

  • Do not ship AWS credentials in browser or untrusted client applications.
  • Prefer temporary credentials, roles, profiles, and workload identities over long-lived keys.
  • Do not log access keys, secret keys, session tokens, bearer tokens, or signed authorization headers. The SDK redacts Authorization and X-Amz-Security-Token from its HTTP logs.
  • OpenAI workload identity federation and AWS Bedrock SigV4 are separate authentication systems.