> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Amazon Bedrock with the AI Gateway

> Learn how to call models on Amazon Bedrock through the ngrok AI Gateway with a Bedrock API key from your own AWS account.

[Amazon Bedrock](https://aws.amazon.com/bedrock/) runs models from Anthropic, Amazon, and open-weight labs in your AWS account.
The gateway accepts these APIs for Bedrock models:

* Anthropic Messages: send requests to `/v1/messages`.
  They reach Claude Haiku 4.5, Claude Sonnet 4.6, Claude Opus 4.5, and Claude Opus 4.6 through InvokeModel, streaming included.
* Bedrock InvokeModel: send requests to `/model/<MODEL_ID>/invoke`, or to `/model/<MODEL_ID>/invoke-with-response-stream` for a stream.
* Bedrock Converse: send requests to `/model/<MODEL_ID>/converse`, or to `/model/<MODEL_ID>/converse-stream` for a stream.
* OpenAI Chat Completions and Responses: send requests to `/v1/chat/completions` or `/v1/responses`.
  They reach [Gemma 4](#gemma-4).

Chat Completions and Responses requests don't reach the Claude models or the [Converse models](#available-models) yet.

> [!NOTE]
>
> Even though Amazon Bedrock is a **built-in provider**, it still requires you to **bring your own key** because you can't pay for it with credits at this time.

## Setup

### 1. Create an access key

Follow the [quickstart](https://ngrok.com/docs/ai-gateway/quickstart.md) to create an access key in [app.ngrok.ai](https://app.ngrok.ai).

### 2. Turn on model access

In commercial AWS regions, AWS turns on access to most models the first time your account calls them.
For a model sold through AWS Marketplace, that first call starts a Marketplace subscription, which can take up to 15 minutes.
The identity that makes the call needs `aws-marketplace:Subscribe`, `aws-marketplace:Unsubscribe`, and `aws-marketplace:ViewSubscriptions`.
The GPT OSS models and the Amazon, MiniMax, Mistral, Moonshot AI, Qwen, and Z.ai models don't need a subscription.

Before you call a Claude model, complete the Anthropic First Time Use (FTU) form.
AWS requires it for Anthropic models earlier than Claude Opus 4.7, which covers every Claude model on this page.
Open the Anthropic model in **Model catalog** in the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/) to find it.
You submit the form once per AWS account, or once in your AWS organization's management account.
See [Access Amazon Bedrock foundation models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html).

### 3. Create a Bedrock API key

In the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/), open **API keys** and choose the **Long-term API keys** tab.
Click **Generate long-term API keys**, choose a time in **API key expiration**, and click **Generate**.
AWS shows the key only once, so copy it now.

Use a long-term key.
A short-term key expires with your console session, after 12 hours at most, and works only in the region that made it.

AWS attaches the `AmazonBedrockLimitedAccess` managed policy to the IAM user behind the key.
That policy already has the permissions the gateway needs.
AWS recommends API keys for exploration and short-term credentials for production.
See [Generate Amazon Bedrock API keys](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys-generate.html).

### 4. Add the key to ngrok

[Add a provider key](https://ngrok.com/docs/ai-gateway/guides/attaching-provider-keys.md#add-a-provider-key) for Amazon Bedrock.
A key you add in the dashboard uses the `us-east-1` region.
To use another region, add the key with the [Provider Keys API](https://ngrok.com/docs/ai-gateway/api-reference/provider-keys/create.md) and set `aws.region`:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl -X POST https://api.ngrok.ai/provider-keys \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"providerId": "bedrock", "name": "Bedrock eu-west-1", "value": "<BEDROCK_API_KEY>", "aws": {"region": "eu-west-1"}}'
```

The API refuses a region where Bedrock doesn't run.
See [Regions](#regions) for how the region picks where requests go.

### 5. Create a configuration

[Create an access key configuration](https://ngrok.com/docs/ai-gateway/guides/access-key-configurations.md#create-a-configuration) with a `bedrock` routing rule and allow Amazon Bedrock in the access scope.

### 6. Assign and send requests

Assign the configuration to your access key and send requests with your access key:

```python Python theme={"theme":{"light":"css-variables","dark":"css-variables"}}
import anthropic

client = anthropic.Anthropic(
    base_url="https://gateway.ngrok.ai",
    api_key="ng-xxxxx-g1-xxxxx",  # Access key
)

message = client.messages.create(
    model="bedrock:anthropic/claude-haiku-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)
```

```bash cURL theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl https://gateway.ngrok.ai/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: ng-xxxxx-g1-xxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model": "bedrock:anthropic/claude-haiku-4-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello!"}]}'
```

The `bedrock:` prefix keeps the request on Amazon Bedrock.
A bare `anthropic/claude-haiku-4-5` goes to Anthropic first.

## Scope down the key's IAM policy

The default `AmazonBedrockLimitedAccess` policy covers every call the gateway makes.
If you replace it with a narrower policy, the key's IAM user needs at least these permissions:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"}}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "bedrock:CallWithBearerToken",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": [
        "arn:aws:bedrock:*::foundation-model/*",
        "arn:aws:bedrock:*:<ACCOUNT_ID>:inference-profile/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "bedrock-mantle:CallWithBearerToken",
        "bedrock-mantle:CreateInference"
      ],
      "Resource": "*"
    }
  ]
}
```

`bedrock:CallWithBearerToken` lets the key call Bedrock as a bearer token.
Converse requests use the same two invoke permissions as InvokeModel requests.
An inference profile can run a request in any region of its geography, so the policy covers every region.
The `bedrock-mantle` statement covers Gemma 4, which runs on the bedrock-mantle endpoint.
To accept only long-term keys, add a condition on `bedrock:BearerTokenType` with the value `LONG_TERM`.
A deny on `bedrock:CallWithBearerToken` alone doesn't block API keys on bedrock-mantle.
To block them there too, also deny `bedrock-mantle:CallWithBearerToken`.
See [Revoke Amazon Bedrock API keys](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys-revoke.html).
See [Actions defined by Amazon Bedrock](https://docs.aws.amazon.com/service-authorization/latest/reference/list_bedrock.html).

## Regions

Each Bedrock key sends requests to one AWS region.
A key with no region uses `us-east-1`.

The key's region picks the AWS endpoint and the model ID the gateway sends.
The endpoint is `bedrock-runtime.<REGION>.amazonaws.com`, or `bedrock-mantle.<REGION>.api.aws` for Gemma 4.
The gateway sends the model's in-region ID when the model runs in that region, and the inference profile for the region's geography otherwise.
The key's region wins over the `us.` in a model ID.
For example, a key in `eu-west-1` sends a request for `us.anthropic.claude-haiku-4-5-20251001-v1:0` through the `eu.` inference profile.
A model ID with a different geography prefix, such as `eu.anthropic.claude-haiku-4-5-20251001-v1:0`, uses only keys in that geography.

Gemma 4 runs in-region only, with no inference profile.
Keys in `us-east-1`, `us-east-2`, `us-west-2`, and `eu-central-1` serve it.
GLM-4.7, GLM-5, Ministral 3B, and Qwen3 Coder 30B A3B Instruct serve `us-east-1` keys only.
The gateway doesn't support `global.` model IDs.

When none of your keys is in a region that serves the model, the gateway returns a `400` error with `ERR_NGROK_AI_GATEWAY_MODEL_REGION_UNSUPPORTED`:

```text theme={"theme":{"light":"css-variables","dark":"css-variables"}}
No Bedrock key region serves model '<MODEL_ID>'. Key regions: <REGIONS>. Add a Bedrock key in a region that serves the model.
```

## Native Bedrock requests

Point an AWS SDK at `https://gateway.ngrok.ai` and send your ngrok access key as the bearer token.
The AWS SDKs read the bearer token from the `AWS_BEARER_TOKEN_BEDROCK` environment variable.
When `AWS_BEARER_TOKEN_BEDROCK` is set, boto3 sends the bearer token even if your shell also sets `AWS_PROFILE`.
The gateway returns errors in the Bedrock error format.
Name the model by its Bedrock model ID, such as `us.anthropic.claude-haiku-4-5-20251001-v1:0`.

Send an InvokeModel request to a Claude model:

```python Python theme={"theme":{"light":"css-variables","dark":"css-variables"}}
import json

import boto3

# export AWS_BEARER_TOKEN_BEDROCK=ng-xxxxx-g1-xxxxx
client = boto3.client(
    "bedrock-runtime",
    region_name="us-east-1",  # the SDK needs a region; your ngrok key's region decides where the request goes
    endpoint_url="https://gateway.ngrok.ai",
)

response = client.invoke_model(
    modelId="us.anthropic.claude-haiku-4-5-20251001-v1:0",
    body=json.dumps({
        "anthropic_version": "bedrock-2023-05-31",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "Hello!"}],
    }),
)
print(json.loads(response["body"].read()))
```

```bash cURL theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl https://gateway.ngrok.ai/model/us.anthropic.claude-haiku-4-5-20251001-v1:0/invoke \
  -H "Authorization: Bearer ng-xxxxx-g1-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"anthropic_version": "bedrock-2023-05-31", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello!"}]}'
```

Send a Converse request to a Converse model:

```python Python theme={"theme":{"light":"css-variables","dark":"css-variables"}}
import boto3

# export AWS_BEARER_TOKEN_BEDROCK=ng-xxxxx-g1-xxxxx
client = boto3.client(
    "bedrock-runtime",
    region_name="us-east-1",  # the SDK needs a region; your ngrok key's region decides where the request goes
    endpoint_url="https://gateway.ngrok.ai",
)

response = client.converse(
    modelId="openai.gpt-oss-20b-1:0",
    messages=[{"role": "user", "content": [{"text": "Hello!"}]}],
)
```

```bash cURL theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl https://gateway.ngrok.ai/model/openai.gpt-oss-20b-1:0/converse \
  -H "Authorization: Bearer ng-xxxxx-g1-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": [{"text": "Hello!"}]}]}'
```

The SDK needs a region, but the region of your Bedrock key in ngrok decides where the request goes.

### Stream responses

Send stream requests to `/model/<MODEL_ID>/converse-stream` or `/model/<MODEL_ID>/invoke-with-response-stream`.
The gateway returns the stream as AWS event stream frames, which the AWS SDKs read.

```python Converse theme={"theme":{"light":"css-variables","dark":"css-variables"}}
import boto3

# export AWS_BEARER_TOKEN_BEDROCK=ng-xxxxx-g1-xxxxx
client = boto3.client(
    "bedrock-runtime",
    region_name="us-east-1",  # the SDK needs a region; your ngrok key's region decides where the request goes
    endpoint_url="https://gateway.ngrok.ai",
)

response = client.converse_stream(
    modelId="openai.gpt-oss-20b-1:0",
    messages=[{"role": "user", "content": [{"text": "Hello!"}]}],
)

for event in response["stream"]:
    if "contentBlockDelta" in event:
        print(event["contentBlockDelta"]["delta"].get("text", ""), end="")
```

```python InvokeModel theme={"theme":{"light":"css-variables","dark":"css-variables"}}
import json

import boto3

# export AWS_BEARER_TOKEN_BEDROCK=ng-xxxxx-g1-xxxxx
client = boto3.client(
    "bedrock-runtime",
    region_name="us-east-1",  # the SDK needs a region; your ngrok key's region decides where the request goes
    endpoint_url="https://gateway.ngrok.ai",
)

response = client.invoke_model_with_response_stream(
    modelId="us.anthropic.claude-haiku-4-5-20251001-v1:0",
    body=json.dumps({
        "anthropic_version": "bedrock-2023-05-31",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "Hello!"}],
    }),
)

for event in response["body"]:
    chunk = json.loads(event["chunk"]["bytes"])
    if chunk["type"] == "content_block_delta":
        print(chunk["delta"].get("text", ""), end="")
```

## Gemma 4

Amazon Bedrock serves Gemma 4 through its OpenAI-compatible API.
Send Chat Completions or Responses requests with `bedrock:google/gemma-4-31b-it` or `bedrock:google/gemma-4-26b-a4b-it`:

```bash Chat Completions theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl https://gateway.ngrok.ai/v1/chat/completions \
  -H "Authorization: Bearer ng-xxxxx-g1-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "bedrock:google/gemma-4-31b-it", "messages": [{"role": "user", "content": "Hello!"}]}'
```

```bash Responses theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl https://gateway.ngrok.ai/v1/responses \
  -H "Authorization: Bearer ng-xxxxx-g1-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "bedrock:google/gemma-4-31b-it", "input": "Hello!"}'
```

Google and LLM API also serve Gemma 4, so the `bedrock:` prefix keeps the request on Amazon Bedrock.

Bedrock keeps Responses output by default.
The gateway sends `store: false`, so Bedrock doesn't keep it.
The gateway removes `store` and `previous_response_id` from a Responses request to Gemma 4 and lists them in the `Ngrok-AIG-Removed-Params` [response header](https://ngrok.com/docs/ai-gateway/how-it-works.md#response-headers), so a request can't continue an earlier response on Bedrock.

## Try Amazon Bedrock before Anthropic

A bare Claude model ID, such as `anthropic/claude-haiku-4-5`, goes to Anthropic first.
The `bedrock:` prefix pins a request to Amazon Bedrock, with no fallback to another provider.

To try Amazon Bedrock first and fall back to Anthropic, create a [virtual model](https://ngrok.com/docs/ai-gateway/guides/virtual-models.md) that lists both:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl -X POST https://api.ngrok.ai/virtual-models \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "claude-haiku-bedrock-first",
    "models": [
      "bedrock:anthropic/claude-haiku-4-5",
      "anthropic:anthropic/claude-haiku-4-5"
    ]
  }'
```

Send `claude-haiku-bedrock-first` as the model in a Messages request.

> [!NOTE]
>
> In an access key configuration, a [model rule](https://ngrok.com/docs/ai-gateway/guides/access-key-configurations.md#routing-rules) names the catalog ID with the provider prefix, such as `bedrock:anthropic/claude-haiku-4-5`.
> A rule that names a Bedrock model ID, such as `us.anthropic.claude-haiku-4-5-20251001-v1:0`, doesn't match requests yet.

## Available models

See the [model catalog](https://ngrok.com/docs/ai-gateway/reference/model-catalog.md#amazon-bedrock).
The gateway sends Amazon Bedrock only the models in the catalog.

Each model takes these request formats:

* Claude Haiku 4.5, Claude Sonnet 4.6, Claude Opus 4.5, and Claude Opus 4.6: Messages and Bedrock InvokeModel.
* Gemma 4 31B and Gemma 4 26B A4B: Chat Completions and Responses.
* Every other model: Bedrock Converse.
  This page calls them the Converse models.

## Troubleshooting

| Symptom | Fix |
| - | - |
| [`ERR_NGROK_27226`](https://ngrok.com/docs/ai-gateway/reference/error-codes#err_ngrok_27226) | The API you called doesn't reach that model. Send Messages or InvokeModel requests to the Claude models, Chat Completions or Responses requests to Gemma 4, and Converse requests to the other models. See [Available models](#available-models). |
| `ERR_NGROK_AI_GATEWAY_MODEL_REGION_UNSUPPORTED` | None of your Bedrock keys is in a region that serves the model. Add a key in a region that serves it. See [Regions](#regions). |
| `403` error that names `bedrock:CallWithBearerToken` and a service control policy | A service control policy in your AWS organization denies `bedrock:CallWithBearerToken`, which blocks API keys for the Claude and Converse models. Ask your AWS administrator to allow `bedrock:CallWithBearerToken` for the account. |
| `403` `AccessDeniedException` that says the model isn't available or needs AWS Marketplace actions | [Turn on model access](#setup) for the model in that AWS account. After you submit the FTU form, the model can stay pending and keep returning this error, so wait and retry. The gateway doesn't try your other Bedrock keys, because keys in the same account get the same refusal. |

## Next steps

* [Provider keys](https://ngrok.com/docs/ai-gateway/guides/attaching-provider-keys.md)
* [Access key configurations](https://ngrok.com/docs/ai-gateway/guides/access-key-configurations.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.