Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

fix/Bedrock-bearer-token-env · L-260927-06f4db (#1291)

Louis Choquel034019600610
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 19e42bbea..4c3474c73 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,7 @@
- **A composite nested in an `Anything` value or in another composite survives transport**: its components, a nested composite and a list of composites included, come back through hydration as typed contents, where they came back as dicts carrying class markers.
- **The result files of an `Anything` output render its value**: a delivery whose main output is `Anything` renders `main_stuff.json`, `.md` and `.html` from the hydrated content, where it fell back to a raw dump of the transport form.
- **A prebuilt list is refused where one value belongs**: a `ListContent` given as an item of a plural input, or as the content of an `Anything` envelope at a single input, is refused instead of being stored nested or in a singular slot.
+- **`bedrock_anthropic` models run with `AWS_BEARER_TOKEN_BEDROCK` set**: under `bedrock_access_variant = "aws_access"`, the default, Anthropic models on Bedrock sign their requests with the configured AWS access keys and ignore a Bedrock bearer token in the environment, where every one of them used to fail at client construction with a raw `ValueError`. When the access keys are missing and the environment carries such a token, the `AwsCredentialsError` now says so and names `bedrock_access_variant = "bedrock_token"` as the way to authenticate with a bearer token.
## [v0.68.0] - 2026-09-27
diff --git a/docs/configuration/config-technical/aws-config.md b/docs/configuration/config-technical/aws-config.md
index 8c9388800..1b8c6c582 100644
--- a/docs/configuration/config-technical/aws-config.md
+++ b/docs/configuration/config-technical/aws-config.md
@@ -15,9 +15,11 @@ The AWS configuration controls how Pipelex authenticates with AWS services. It s
```toml
[runtime.aws]
api_key_method = "env" # or "secret_provider"
-bedrock_access_variant = "bedrock_token" # or "aws_access"
+bedrock_access_variant = "aws_access" # or "bedrock_token"
```
+`api_key_method` says where the credentials are read from, and `bedrock_access_variant` says which credentials Anthropic models on Amazon Bedrock authenticate with. The values above are the defaults.
+
### Environment Variables Method (`"env"`)
When using `api_key_method = "env"`, Pipelex expects the following environment variables:
@@ -25,6 +27,8 @@ When using `api_key_method = "env"`, Pipelex expects the following environment v
- `AWS_SECRET_ACCESS_KEY`: Your AWS secret access key
- `AWS_REGION`: Your AWS region
+Under `bedrock_access_variant = "bedrock_token"`, Anthropic models on Bedrock authenticate with `AWS_BEARER_TOKEN_BEDROCK` instead of the two access keys, and still take their region from `AWS_REGION` (see [Bedrock Access Variant](#bedrock-access-variant)).
+
Example `.env` file:
```env
AWS_ACCESS_KEY_ID=your_access_key_id
@@ -51,6 +55,26 @@ When using `api_key_method = "secret_provider"`, Pipelex will:
2. Store your AWS credentials in your secret provider
3. Ensure your secret provider is properly authenticated
+## Bedrock Access Variant
+
+`bedrock_access_variant` chooses how the `bedrock_anthropic` SDK, which serves the Claude models of the `bedrock` backend, authenticates with Amazon Bedrock:
+
+- **`"aws_access"`** (the default) signs every request with AWS Signature Version 4, from `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_REGION`.
+- **`"bedrock_token"`** sends a Bedrock API key as a bearer token, read from `AWS_BEARER_TOKEN_BEDROCK`. The access keys are not read, and the region comes from `AWS_REGION` in the environment, then from your AWS profile, and otherwise defaults to `us-east-1`.
+
+`api_key_method` decides where the credentials come from: the environment under `"env"`, your secret provider under `"secret_provider"`. The region under `"bedrock_token"` is the exception, since it is always read from the environment or the AWS profile, never from a secret provider.
+
+### The configured variant wins
+
+`AWS_BEARER_TOKEN_BEDROCK` is the standard name for a Bedrock API key, which AWS SDKs and other tools such as Claude Code on Bedrock read, so it is often set in a shell for reasons that have nothing to do with Pipelex. Pipelex never lets it override your configuration:
+
+- Under `"aws_access"`, every `bedrock_anthropic` request is signed with the configured access keys, and a bearer token in the environment is ignored. If the access keys are missing, Pipelex fails with an `AwsCredentialsError` rather than falling back to the token; when the environment does carry one, that error says so and names `bedrock_access_variant = "bedrock_token"` as the way to authenticate with a bearer token. That variant reads the token from wherever `api_key_method` points, so under `"secret_provider"` the token has to be stored in your secret provider as well.
+- Under `"bedrock_token"`, the token is the only credential used, and the access keys are not read.
+
+### The other Bedrock models
+
+The models of the `bedrock` backend whose `sdk` is not `bedrock_anthropic` do not read `[runtime.aws]`. They follow boto's own credential chain (environment variables, the shared AWS configuration files, an instance or container role) and take their region from the backend's `aws_region` setting. In that chain, a set `AWS_BEARER_TOKEN_BEDROCK` takes precedence over access keys, so for these models a bearer token in the environment is what authenticates.
+
## Dependency Injection
Pipelex uses dependency injection to manage AWS clients and credentials. You can:
diff --git a/pipelex/providers/anthropic/anthropic_bedrock_sigv4.py b/pipelex/providers/anthropic/anthropic_bedrock_sigv4.py
new file mode 100644
index 000000000..fcd184f77
--- /dev/null
+++ b/pipelex/providers/anthropic/anthropic_bedrock_sigv4.py
@@ -0,0 +1,65 @@
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+from anthropic import DEFAULT_MAX_RETRIES, NOT_GIVEN, NotGiven
+from anthropic.lib.bedrock import AsyncAnthropicBedrock
+
+from pipelex.providers.anthropic.anthropic_exceptions import AnthropicFactoryError
+
+
+class AsyncAnthropicBedrockSigV4(AsyncAnthropicBedrock):
+ """A Bedrock client that always signs with SigV4 from the AWS keys it is given, whatever the environment says.
+
+ `AsyncAnthropicBedrock` fills `api_key` from `AWS_BEARER_TOKEN_BEDROCK` whenever it is given none, unconditionally,
+ and then refuses explicit AWS credentials beside it with a `ValueError`. Pipelex's `bedrock_access_variant` is its one
+ statement of which Bedrock credentials to use, so under `aws_access` a token in the environment, typically set for
+ another tool, must not decide anything. This class hands the SDK constructor only the region and the transport
+ options, which never clash, then resets `api_key` to `None` and sets the credentials itself: the SDK's request hook
+ signs with SigV4 whenever `api_key` is `None`, reading exactly these attributes.
+
+ The SDK's `copy` (alias `with_options`) rebuilds the client through `self.__class__` with the stored credentials and
+ `api_key=None`, so a copy takes the same path. Options that later SDK releases add to the constructor and pass through
+ `copy`, such as `middleware` from anthropic 0.108, reach the parent unchanged through `**kwargs`. This couples to four
+ public attributes of the SDK client and to the rule that `api_key is None` means SigV4; `test_anthropic_bedrock_auth.py`
+ guards the coupling on the wire, so an SDK release that changes it fails there at the dependency bump.
+ """
+
+ def __init__(
+ self,
+ *,
+ aws_access_key: str,
+ aws_secret_key: str,
+ aws_region: str,
+ aws_session_token: str | None = None,
+ api_key: str | None = None,
+ base_url: str | httpx.URL | None = None,
+ timeout: float | httpx.Timeout | NotGiven | None = NOT_GIVEN,
+ max_retries: int = DEFAULT_MAX_RETRIES,
+ default_headers: Mapping[str, str] | None = None,
+ default_query: Mapping[str, object] | None = None,
+ http_client: httpx.AsyncClient | None = None,
+ **kwargs: Any,
+ ) -> None:
+ # The parameter exists only because the SDK's `copy` always passes one.
+ if api_key is not None:
+ msg = (
+ "AsyncAnthropicBedrockSigV4 signs with AWS access keys and takes no api_key: "
+ "a Bedrock bearer token belongs to the 'bedrock_token' access variant"
+ )
+ raise AnthropicFactoryError(msg)
+ super().__init__(
+ aws_region=aws_region,
+ base_url=base_url,
+ timeout=timeout,
+ max_retries=max_retries,
+ default_headers=default_headers,
+ default_query=default_query,
+ http_client=http_client,
+ **kwargs,
+ )
+ # The parent has just filled api_key from AWS_BEARER_TOKEN_BEDROCK if it is set: None is what makes it sign with SigV4.
+ self.api_key = None
+ self.aws_access_key = aws_access_key
+ self.aws_secret_key = aws_secret_key
+ self.aws_session_token = aws_session_token
diff --git a/pipelex/providers/anthropic/anthropic_factory.py b/pipelex/providers/anthropic/anthropic_factory.py
index 7348c916b..564c9a351 100644
--- a/pipelex/providers/anthropic/anthropic_factory.py
+++ b/pipelex/providers/anthropic/anthropic_factory.py
@@ -9,6 +9,7 @@ from anthropic.types.document_block_param import DocumentBlockParam
from anthropic.types.image_block_param import ImageBlockParam
from anthropic.types.message_param import MessageParam
+from pipelex import log
from pipelex.cogt.document.prompt_document_utils import prep_prompt_documents
from pipelex.cogt.image.prompt_image_utils import prep_prompt_images
from pipelex.cogt.llm.llm_job import LLMJob
@@ -16,8 +17,11 @@ from pipelex.cogt.model_backends.backend import InferenceBackend
from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategory
from pipelex.config import get_config
from pipelex.plugins.model_handle import ModelHandle
+from pipelex.providers.anthropic.anthropic_bedrock_sigv4 import AsyncAnthropicBedrockSigV4
from pipelex.providers.anthropic.anthropic_exceptions import AnthropicFactoryError
-from pipelex.tools.aws.aws_config import BedrockAccessVariant
+from pipelex.system.environment import get_optional_env
+from pipelex.tools.aws.aws_config import BEDROCK_TOKEN_VAR_NAME, AwsKeyMethod, BedrockAccessVariant
+from pipelex.tools.aws.exceptions import AwsCredentialsError
from pipelex.tools.uri.prepared_file import PreparedFile, PreparedFileBase64, PreparedFileHttpUrl, PreparedFileLocalPath
if TYPE_CHECKING:
@@ -88,10 +92,38 @@ class AnthropicFactory:
aws_config = get_config().runtime.aws
match aws_config.bedrock_access_variant:
case BedrockAccessVariant.AWS_ACCESS:
- aws_access_key_id, aws_secret_access_key, aws_region = aws_config.get_aws_access_keys()
- return AsyncAnthropicBedrock(
- aws_secret_key=aws_secret_access_key,
+ # The configured variant wins over a Bedrock bearer token in the environment, which the SDK
+ # would otherwise pick up and refuse beside the access keys: see AsyncAnthropicBedrockSigV4.
+ is_bedrock_token_in_env = bool(get_optional_env(BEDROCK_TOKEN_VAR_NAME))
+ try:
+ aws_access_key_id, aws_secret_access_key, aws_region = aws_config.get_aws_access_keys()
+ except AwsCredentialsError as exc:
+ if not is_bedrock_token_in_env:
+ raise
+ # The cause's message may or may not end its sentence, depending on where the keys were looked for.
+ cause_message = str(exc).rstrip(".")
+ msg = (
+ f"{cause_message}. The environment sets {BEDROCK_TOKEN_VAR_NAME}, a Bedrock bearer token, which "
+ f'bedrock_access_variant = "{BedrockAccessVariant.AWS_ACCESS}" ignores: to authenticate with a '
+ f'bearer token instead, set bedrock_access_variant = "{BedrockAccessVariant.BEDROCK_TOKEN}" in [runtime.aws].'
+ )
+ match aws_config.api_key_method:
+ case AwsKeyMethod.ENV:
+ pass
+ case AwsKeyMethod.SECRET_PROVIDER:
+ msg += (
+ f' Under api_key_method = "{AwsKeyMethod.SECRET_PROVIDER}", that variant reads '
+ f"{BEDROCK_TOKEN_VAR_NAME} from the secrets provider, not from the environment."
+ )
+ raise AwsCredentialsError(msg) from exc
+ if is_bedrock_token_in_env:
+ log.verbose(
+ f"Ignoring {BEDROCK_TOKEN_VAR_NAME} from the environment: "
+ f'bedrock_access_variant = "{BedrockAccessVariant.AWS_ACCESS}" signs with the configured AWS access keys.'
+ )
+ return AsyncAnthropicBedrockSigV4(
aws_access_key=aws_access_key_id,
+ aws_secret_key=aws_secret_access_key,
aws_region=aws_region,
max_retries=transport_max_retries,
)
diff --git a/tests/unit/pipelex/providers/anthropic/test_anthropic_bedrock_auth.py b/tests/unit/pipelex/providers/anthropic/test_anthropic_bedrock_auth.py
new file mode 100644
index 000000000..493eb7b99
--- /dev/null
+++ b/tests/unit/pipelex/providers/anthropic/test_anthropic_bedrock_auth.py
@@ -0,0 +1,230 @@
+"""Under `bedrock_access_variant = "aws_access"`, the configured AWS keys sign every `bedrock_anthropic` request, whatever the
+environment says.
+
+The anthropic SDK's Bedrock client reads `AWS_BEARER_TOKEN_BEDROCK` whenever it is given no `api_key`, then refuses explicit AWS
+credentials beside it with a raw `ValueError`. That variable is the standard name for a Bedrock API key, which other AWS tooling
+reads, so a developer who keeps one in a shell profile could not run a single `bedrock_anthropic` model under pipelex's default
+configuration. `[runtime.aws]` is pipelex's one statement of where Bedrock credentials come from, so the configured variant wins:
+the factory builds a SigV4-only subclass of the SDK client which drops the token the SDK picked up.
+
+That subclass relies on the SDK's rule that an `api_key` of `None` means SigV4 signing, so these tests check the wire rather than
+the attributes: a request sent through an `httpx.MockTransport` with the variable set must carry a SigV4 `Authorization` header
+naming the configured key id. An SDK release that changes the rule turns them red at the dependency bump.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import httpx
+import pytest
+from anthropic.lib.bedrock import AsyncAnthropicBedrock
+
+from pipelex.plugins.model_handle import ModelHandle
+from pipelex.providers.anthropic.anthropic_bedrock_sigv4 import AsyncAnthropicBedrockSigV4
+from pipelex.providers.anthropic.anthropic_exceptions import AnthropicFactoryError
+from pipelex.providers.anthropic.anthropic_factory import AnthropicFactory
+from pipelex.tools.aws.aws_config import (
+ AWS_ACCESS_KEY_ID_VAR_NAME,
+ AWS_REGION_VAR_NAME,
+ AWS_SECRET_ACCESS_KEY_VAR_NAME,
+ BEDROCK_TOKEN_VAR_NAME,
+ AwsConfig,
+ AwsKeyMethod,
+ BedrockAccessVariant,
+)
+from pipelex.tools.aws.exceptions import AwsCredentialsError
+from pipelex.tools.secrets.exceptions import SecretNotFoundError
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
+_KEY_ID = "AKIAPIPELEXTESTKEY01"
+_SECRET_KEY = "pipelex-test-secret-access-key"
+_REGION = "eu-west-3"
+_ENV_BEARER_TOKEN = "bedrock-bearer-token-from-the-shell"
+_SIGV4_PREFIX = f"AWS4-HMAC-SHA256 Credential={_KEY_ID}/"
+_MODEL = "anthropic.claude-haiku-4-5-20251001-v1:0"
+_MESSAGE_RESPONSE: dict[str, Any] = {
+ "id": "msg_test",
+ "type": "message",
+ "role": "assistant",
+ "model": _MODEL,
+ "content": [{"type": "text", "text": "ok"}],
+ "stop_reason": "end_turn",
+ "stop_sequence": None,
+ "usage": {"input_tokens": 1, "output_tokens": 1},
+}
+
+
+def _model_handle() -> ModelHandle:
+ return ModelHandle(sdk="bedrock_anthropic", backend="bedrock")
+
+
+def _patch_config(
+ mocker: MockerFixture,
+ *,
+ bedrock_access_variant: BedrockAccessVariant,
+ api_key_method: AwsKeyMethod = AwsKeyMethod.ENV,
+) -> None:
+ config = mocker.MagicMock()
+ config.inference.transport_max_retries = 0
+ config.runtime.aws = AwsConfig(api_key_method=api_key_method, bedrock_access_variant=bedrock_access_variant)
+ mocker.patch("pipelex.providers.anthropic.anthropic_factory.get_config", return_value=config)
+
+
+def _set_access_keys_in_env(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv(AWS_ACCESS_KEY_ID_VAR_NAME, _KEY_ID)
+ monkeypatch.setenv(AWS_SECRET_ACCESS_KEY_VAR_NAME, _SECRET_KEY)
+ monkeypatch.setenv(AWS_REGION_VAR_NAME, _REGION)
+
+
+def _recording_transport(seen_authorizations: list[str]) -> httpx.MockTransport:
+ def _handler(request: httpx.Request) -> httpx.Response:
+ seen_authorizations.append(request.headers.get("Authorization", ""))
+ return httpx.Response(200, json=_MESSAGE_RESPONSE)
+
+ return httpx.MockTransport(_handler)
+
+
+async def _send_one_message(client: AsyncAnthropicBedrock) -> None:
+ await client.messages.create(model=_MODEL, max_tokens=8, messages=[{"role": "user", "content": "ping"}])
+
+
+class TestAnthropicBedrockAuth:
+ @pytest.mark.asyncio
+ async def test_sigv4_client_signs_with_the_configured_keys_despite_the_token(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """With the bearer token in the environment, the request still carries a SigV4 signature from the configured key id."""
+ monkeypatch.setenv(BEDROCK_TOKEN_VAR_NAME, _ENV_BEARER_TOKEN)
+ seen_authorizations: list[str] = []
+ async with httpx.AsyncClient(transport=_recording_transport(seen_authorizations)) as http_client:
+ client = AsyncAnthropicBedrockSigV4(
+ aws_access_key=_KEY_ID,
+ aws_secret_key=_SECRET_KEY,
+ aws_region=_REGION,
+ max_retries=0,
+ http_client=http_client,
+ )
+ await _send_one_message(client)
+
+ assert len(seen_authorizations) == 1
+ assert seen_authorizations[0].startswith(_SIGV4_PREFIX)
+ assert not seen_authorizations[0].startswith("Bearer")
+
+ @pytest.mark.asyncio
+ async def test_with_options_copy_signs_the_same_way(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """The SDK's `copy` rebuilds the client through its class, re-reading the environment, and must sign with SigV4 all the same."""
+ monkeypatch.setenv(BEDROCK_TOKEN_VAR_NAME, _ENV_BEARER_TOKEN)
+ client = AsyncAnthropicBedrockSigV4(aws_access_key=_KEY_ID, aws_secret_key=_SECRET_KEY, aws_region=_REGION, max_retries=0)
+ seen_authorizations: list[str] = []
+ # The SDK's copy does not carry a custom http_client over, so the mock transport is passed again.
+ async with httpx.AsyncClient(transport=_recording_transport(seen_authorizations)) as http_client:
+ copied_client = client.with_options(http_client=http_client, timeout=30)
+ await _send_one_message(copied_client)
+
+ assert isinstance(copied_client, AsyncAnthropicBedrockSigV4)
+ assert copied_client.api_key is None
+ assert len(seen_authorizations) == 1
+ assert seen_authorizations[0].startswith(_SIGV4_PREFIX)
+
+ def test_copy_forwards_the_options_the_subclass_does_not_name(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """Later SDK releases pass new options through `copy` (`middleware` from 0.108): the subclass forwards what it does not name."""
+ monkeypatch.setenv(BEDROCK_TOKEN_VAR_NAME, _ENV_BEARER_TOKEN)
+ client = AsyncAnthropicBedrockSigV4(aws_access_key=_KEY_ID, aws_secret_key=_SECRET_KEY, aws_region=_REGION, max_retries=0)
+
+ copied_client = client.copy(_extra_kwargs={"_strict_response_validation": True})
+
+ assert isinstance(copied_client, AsyncAnthropicBedrockSigV4)
+ assert copied_client._strict_response_validation is True # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ assert copied_client.api_key is None
+ assert copied_client.aws_access_key == _KEY_ID
+
+ @pytest.mark.parametrize("token_in_env", [True, False], ids=["token_in_env", "no_token"])
+ def test_factory_builds_the_sigv4_client_under_aws_access(
+ self,
+ mocker: MockerFixture,
+ monkeypatch: pytest.MonkeyPatch,
+ token_in_env: bool,
+ ) -> None:
+ """Under `aws_access` the factory builds the SigV4 client from the configured keys, whether or not the token is set."""
+ _patch_config(mocker, bedrock_access_variant=BedrockAccessVariant.AWS_ACCESS)
+ _set_access_keys_in_env(monkeypatch)
+ if token_in_env:
+ monkeypatch.setenv(BEDROCK_TOKEN_VAR_NAME, _ENV_BEARER_TOKEN)
+ else:
+ monkeypatch.delenv(BEDROCK_TOKEN_VAR_NAME, raising=False)
+
+ client = AnthropicFactory.make_anthropic_client(model_handle=_model_handle(), backend=mocker.MagicMock())
+
+ assert isinstance(client, AsyncAnthropicBedrockSigV4)
+ assert client.api_key is None
+ assert client.aws_access_key == _KEY_ID
+ assert client.aws_secret_key == _SECRET_KEY
+ assert client.aws_region == _REGION
+ assert client.max_retries == 0
+
+ @pytest.mark.asyncio
+ async def test_bedrock_token_variant_sends_the_token_as_bearer(self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch) -> None:
+ """Under `bedrock_token` the factory keeps the plain SDK client, which authenticates with the token as a bearer."""
+ _patch_config(mocker, bedrock_access_variant=BedrockAccessVariant.BEDROCK_TOKEN)
+ monkeypatch.setenv(BEDROCK_TOKEN_VAR_NAME, _ENV_BEARER_TOKEN)
+
+ client = AnthropicFactory.make_anthropic_client(model_handle=_model_handle(), backend=mocker.MagicMock())
+
+ assert isinstance(client, AsyncAnthropicBedrock)
+ assert not isinstance(client, AsyncAnthropicBedrockSigV4)
+ assert client.api_key == _ENV_BEARER_TOKEN
+ seen_authorizations: list[str] = []
+ async with httpx.AsyncClient(transport=_recording_transport(seen_authorizations)) as http_client:
+ await _send_one_message(client.with_options(http_client=http_client))
+
+ assert seen_authorizations == [f"Bearer {_ENV_BEARER_TOKEN}"]
+
+ @pytest.mark.parametrize("token_in_env", [True, False], ids=["token_in_env", "no_token"])
+ @pytest.mark.parametrize(
+ ("api_key_method", "expects_secrets_provider_note"),
+ [
+ pytest.param(AwsKeyMethod.ENV, False, id="env"),
+ pytest.param(AwsKeyMethod.SECRET_PROVIDER, True, id="secret_provider"),
+ ],
+ )
+ def test_missing_keys_hint_at_the_token_only_when_it_is_set(
+ self,
+ mocker: MockerFixture,
+ monkeypatch: pytest.MonkeyPatch,
+ api_key_method: AwsKeyMethod,
+ expects_secrets_provider_note: bool,
+ token_in_env: bool,
+ ) -> None:
+ """Missing access keys raise `AwsCredentialsError`, naming the bearer token and the `bedrock_token` variant only when it is set."""
+ _patch_config(mocker, bedrock_access_variant=BedrockAccessVariant.AWS_ACCESS, api_key_method=api_key_method)
+ for var_name in (AWS_ACCESS_KEY_ID_VAR_NAME, AWS_SECRET_ACCESS_KEY_VAR_NAME, AWS_REGION_VAR_NAME):
+ monkeypatch.delenv(var_name, raising=False)
+ # A secrets provider that holds none of the keys, as a vault missing them would.
+ mocker.patch("pipelex.tools.aws.aws_config.get_secret", side_effect=SecretNotFoundError("Secret not found"))
+ if token_in_env:
+ monkeypatch.setenv(BEDROCK_TOKEN_VAR_NAME, _ENV_BEARER_TOKEN)
+ else:
+ monkeypatch.delenv(BEDROCK_TOKEN_VAR_NAME, raising=False)
+
+ with pytest.raises(AwsCredentialsError) as exc_info:
+ AnthropicFactory.make_anthropic_client(model_handle=_model_handle(), backend=mocker.MagicMock())
+
+ message = str(exc_info.value)
+ if token_in_env:
+ cause = exc_info.value.__cause__
+ assert isinstance(cause, AwsCredentialsError)
+ assert message.startswith(f"{str(cause).rstrip('.')}. The environment sets {BEDROCK_TOKEN_VAR_NAME}")
+ assert BEDROCK_TOKEN_VAR_NAME in message
+ assert f'bedrock_access_variant = "{BedrockAccessVariant.BEDROCK_TOKEN}"' in message
+ assert _ENV_BEARER_TOKEN not in message
+ # Under secret_provider, the bedrock_token variant reads the token from the secrets provider, and the hint says so.
+ assert ("from the secrets provider" in message) == expects_secrets_provider_note
+ else:
+ assert BEDROCK_TOKEN_VAR_NAME not in message
+ assert BedrockAccessVariant.BEDROCK_TOKEN not in message
+
+ def test_sigv4_client_refuses_an_api_key(self) -> None:
+ """The SigV4 client exists to sign with the access keys, so handing it a token is a mistake it refuses."""
+ with pytest.raises(AnthropicFactoryError, match="api_key"):
+ AsyncAnthropicBedrockSigV4(aws_access_key=_KEY_ID, aws_secret_key=_SECRET_KEY, aws_region=_REGION, api_key="some-token")
diff --git a/wip/bedrock-bearer-token-env/design.md b/wip/bedrock-bearer-token-env/design.md
new file mode 100644
index 000000000..ebc24e6ba
--- /dev/null
+++ b/wip/bedrock-bearer-token-env/design.md
@@ -0,0 +1,64 @@
+---
+status: landed
+item: L-260927-06f4db
+---
+
+# The configured Bedrock access variant wins over `AWS_BEARER_TOKEN_BEDROCK`
+
+## The bug, verified
+
+With `[runtime.aws] bedrock_access_variant = "aws_access"`, which is the shipped default in `pipelex/pipelex.toml`, `AnthropicFactory.make_anthropic_client` builds `AsyncAnthropicBedrock(aws_access_key=…, aws_secret_key=…, aws_region=…)` and passes no `api_key`. The anthropic SDK's Bedrock client then fills `api_key` from `AWS_BEARER_TOKEN_BEDROCK` and refuses the combination with explicit credentials:
+
+```
+ValueError Cannot specify both `api_key` and AWS credentials (`aws_access_key`, `aws_secret_key`, `aws_session_token`, `aws_profile`)
+```
+
+Reproduced offline against anthropic 0.99.0 with `AWS_BEARER_TOKEN_BEDROCK=dummy`: the constructor raises exactly that, and the same construction without the variable succeeds. The lookup is unconditional in the SDK (`if api_key is None: api_key = os.environ.get("AWS_BEARER_TOKEN_BEDROCK")`, in both the sync and async clients), and it is unchanged on the SDK's `main` at 1.8.0, so no upgrade fixes it. Passing an empty string does not help either: `""` is not `None`, so it skips the lookup and then trips the same refusal.
+
+The raw `ValueError` escapes pipelex's error model at client construction, for every `bedrock_anthropic` model. The variable is not exotic: it is the standard name for a Bedrock API key, which AWS tooling and Claude Code on Bedrock read, so a developer who configured one of those in a shell profile cannot run a single `bedrock_anthropic` model under pipelex's default configuration.
+
+## Where else the variable reaches
+
+- **`bedrock_anthropic` under `bedrock_token`** has no clash. Pipelex reads the token itself, from `AWS_BEARER_TOKEN_BEDROCK` under `api_key_method = "env"` or from the secrets provider under `"secret_provider"`, and passes it as `api_key` with no AWS credentials.
+- **The native Bedrock clients** (`bedrock_aioboto3`, renamed `bedrock_aiobotocore` by L-260927-61a69f, and `bedrock_boto3`) never read `[runtime.aws]` at all, and botocore prefers bearer auth for the `bedrock` signing name whenever the variable is set and no signature version is set in code — explicit access keys do not count. An offline probe capturing the `Authorization` header on a `converse` call shows `Bearer dummy` both with the default chain and with explicit keys, and SigV4 only once `Config(signature_version="v4")` is set. That path fails silently rather than loudly, and deciding it needs a question this item does not have to answer (whether to give up boto's default credential chain), so it is filed as its own bug, L-260928-bfd13b, blocked on the aiobotocore swap that renames its files.
+
+## Decision: the configured variant wins
+
+The item allows two outcomes: turn the clash into a configuration error, or decide which one wins and say so. **Pipelex's `bedrock_access_variant` wins.** Under `aws_access`, a `bedrock_anthropic` client signs every request with SigV4 from the credentials `[runtime.aws]` sourced, and an `AWS_BEARER_TOKEN_BEDROCK` in the environment is ignored.
+
+Why this rather than a refusal:
+
+- **`[runtime.aws]` is pipelex's one statement of where Bedrock credentials come from.** Under `api_key_method = "secret_provider"` the user chose the secrets provider precisely so that ambient environment variables would not matter; an SDK lookup that bypasses it contradicts that choice, and refusing on it would make the contradiction pipelex's own rule.
+- **A refusal punishes the common case.** The variable is typically set for a different tool, the variant is the default rather than something the user typed, and the remedy a refusal would ask for — removing a variable from the process environment for pipelex alone — is awkward in a shell and impossible from a `.env` file, since an empty value still clashes.
+- **Letting the configured variant win has no harmful outcome.** Either the access keys are there and the call works with them, or they are missing and pipelex already raises `AwsCredentialsError` — which this change extends to say that a bearer token is present and how to use it. Nothing ever runs on credentials the user did not configure.
+
+Rejected alternatives:
+
+- **A configuration error naming both.** Sound, and the cheapest to build, but it blocks the common case for the reasons above. It remains the fallback if the mechanism below proves unmaintainable against a future SDK.
+- **Masking the variable while the client is constructed.** `os.environ` is process-global, so any other thread reading it during construction sees it disappear; and `with_options` re-runs the constructor later, re-reading the variable, so the mask would have to be repeated at every copy.
+- **Only translating the `ValueError` into a pipelex error.** That is the refusal with extra steps, and it keys on an SDK message string.
+
+## Mechanism
+
+A small subclass of `AsyncAnthropicBedrock` in `pipelex/providers/anthropic/`, used only for the `aws_access` branch. Its constructor passes the SDK nothing but the region and the transport options, which never clashes, then sets `api_key` to `None` and assigns the AWS credentials. The SDK's request hook signs with SigV4 whenever `api_key` is `None`, reading exactly those attributes. The subclass is still an `AsyncAnthropicBedrock`, so the worker's `isinstance` check and `instructor.from_anthropic` accept it unchanged.
+
+`with_options` (the SDK's `copy`) rebuilds the client through `self.__class__(…)` with the stored credentials and `api_key=None`, so a copy takes the same path. An offline probe confirmed it: a client built this way and its `with_options` copy both sent `AWS4-HMAC-SHA256 Credential=<key id>/…` with `AWS_BEARER_TOKEN_BEDROCK` set. The probe also showed that the SDK's `copy` does not carry a custom `http_client` over unless one is passed again, which matters to the tests, not to production.
+
+The constructor refuses a non-`None` `api_key`: the class exists to sign with SigV4, and a caller handing it a token wants the other variant.
+
+The cost is coupling to four public attributes of the SDK client (`api_key`, `aws_access_key`, `aws_secret_key`, `aws_session_token`) and to the rule that `api_key is None` means SigV4. The guard is a behavioural test on the wire, not on the attributes: a request sent through an `httpx.MockTransport` with the variable set must carry a SigV4 `Authorization` header naming the configured key id. An SDK release that changes either the attributes or the rule turns that test red at the dependency bump.
+
+## What the user sees
+
+- **The docs say which wins.** `docs/configuration/config-technical/aws-config.md` gains a section on `bedrock_access_variant`: what each variant reads (it documents neither today, and its sample shows `bedrock_token` although `aws_access` is the default), that under `aws_access` pipelex signs `bedrock_anthropic` requests with the configured keys and ignores `AWS_BEARER_TOKEN_BEDROCK`, and that the native Bedrock clients currently follow boto's own credential chain, in which that variable wins — stated as today's behaviour, pointing at nothing volatile.
+- **The missing-keys error points at the token.** When `aws_access` cannot find its keys and `AWS_BEARER_TOKEN_BEDROCK` is set, the `AwsCredentialsError` raised for a `bedrock_anthropic` client adds that the environment carries a Bedrock bearer token and that `bedrock_access_variant = "bedrock_token"` uses it. That is the one situation where a user plausibly meant the token.
+- **A verbose log line** records, when the variable is set under `aws_access`, that it is being ignored. Not a warning: the outcome is never harmful, and a developer who keeps the variable for another tool would otherwise read the same warning on every run.
+
+## Noticed, not in scope
+
+These neighbouring gaps turned up while reading this code. None is the clash, and closing any of them would change behaviour someone may rely on or belongs to a dependency bump, so they are recorded here rather than folded in:
+
+- **`bedrock_token` passes no region.** The SDK then infers one from `AWS_REGION`, the boto profile, or `us-east-1`, so under `api_key_method = "secret_provider"` a region stored with the secrets is ignored.
+- **`aws_access` passes no session token.** `get_aws_access_keys` reads neither `AWS_SESSION_TOKEN` nor its secret, so temporary STS credentials cannot sign a `bedrock_anthropic` request.
+- **The SDK's `copy` drops `aws_profile`.** Upstream, and harmless to pipelex, which never passes a profile.
+- **anthropic 1.x moves to `httpx2`.** Its base client refuses `httpx` objects, so at that bump the subclass's `httpx` type hints and the wire tests' `httpx.MockTransport` change with the rest of pipelex's anthropic usage; the wire tests turning red there is the tripwire working, not a regression.
diff --git a/wip/bedrock-bearer-token-env/plan.md b/wip/bedrock-bearer-token-env/plan.md
new file mode 100644
index 000000000..04d4a48a0
--- /dev/null
+++ b/wip/bedrock-bearer-token-env/plan.md
@@ -0,0 +1,38 @@
+---
+status: landed
+item: L-260927-06f4db
+---
+
+# Plan: the configured Bedrock access variant wins over `AWS_BEARER_TOKEN_BEDROCK`
+
+The decisions and their rationale are in [`design.md`](design.md). One phase, on `fix/Bedrock-bearer-token-env` from `dev`. It touches only `pipelex/providers/anthropic/`, the docs and the changelog, none of which the in-flight `chore/Bumping` branch (L-260927-56ef15, L-260927-61a69f) changes, so it does not wait for that branch. The native Bedrock path is L-260928-bfd13b and is not part of this plan.
+
+## Tests first
+
+A new `tests/unit/pipelex/providers/anthropic/test_anthropic_bedrock_auth.py`, offline, with a module docstring stating the rule it pins: under `aws_access` the configured keys sign, whatever the environment says. `get_config` is patched as in `test_anthropic_client_auth.py`, with `runtime.aws` a real `AwsConfig` and the variables set through `monkeypatch.setenv`.
+
+- [x] **The wire carries SigV4 with the variable set.** The SigV4 client, given an `httpx.AsyncClient` over an `httpx.MockTransport`, sends a `messages.create` whose `Authorization` header starts with `AWS4-HMAC-SHA256 Credential=<the configured key id>/` and never with `Bearer`.
+- [x] **A `with_options` copy signs the same way**, the mock transport passed again, since the SDK's `copy` does not carry a custom `http_client` over.
+- [x] **The factory builds that client under `aws_access`**, with the variable set and with it unset: it returns the SigV4 subclass, `api_key` is `None`, and the region and key id are the configured ones. This is the test that fails today with the `ValueError`.
+- [x] **`bedrock_token` is unchanged**: the factory passes the token as `api_key`, and a request carries `Bearer <token>`.
+- [x] **Missing keys with the token present** raise `AwsCredentialsError` whose message names `AWS_BEARER_TOKEN_BEDROCK` and `bedrock_token`; with the token absent, the message carries no such hint.
+- [x] **The subclass refuses a non-`None` `api_key`.**
+
+## Implementation
+
+- [x] `pipelex/providers/anthropic/anthropic_bedrock_sigv4.py`: the `AsyncAnthropicBedrock` subclass. Its constructor takes the credentials and the region as keywords, passes the SDK the region and the remaining options only, then sets `api_key = None` and the three credential attributes. Its docstring carries the why: the SDK's unconditional lookup, and the wire test that guards the coupling.
+- [x] `AnthropicFactory.make_anthropic_client`, `aws_access` branch: build the subclass; log at verbose level when `AWS_BEARER_TOKEN_BEDROCK` is set and ignored; when `get_aws_access_keys` raises `AwsCredentialsError` and the variable is set, re-raise it `from` the original with the hint appended. The environment is read through `pipelex.system.environment`, and the variable's name through `BEDROCK_TOKEN_VAR_NAME` in `pipelex/tools/aws/aws_config.py`, never a new literal.
+- [x] Mutation-check the tests: drop the `api_key = None` assignment and watch the wire test go red; restore by re-applying the edit, never with `git checkout`. Dropping it turned the two wire tests and the factory test with the token set red; the factory's missing-keys hint was seen red before it existed.
+
+## Docs and changelog
+
+- [x] `docs/configuration/config-technical/aws-config.md`: a `bedrock_access_variant` section covering both variants, the variables each reads, which one wins under `aws_access` for `bedrock_anthropic`, and how the native Bedrock clients behave today. Correct the sample so it shows the default `aws_access` and names the alternative. MkDocs rules: a blank line before every list.
+- [x] `CHANGELOG.md`, `[Unreleased]` under `### Fixed`: one bold-labelled entry saying that `bedrock_anthropic` models under `aws_access` sign with the configured keys when `AWS_BEARER_TOKEN_BEDROCK` is set, where they used to fail at client construction with a raw `ValueError`.
+
+## Checkpoint: ready for review
+
+- [x] `make agent-check`, with the changes staged first since the drift digest reads the index; handle any drift contract the anthropic or docs change opens.
+- [x] `make agent-test`.
+- [ ] Optional live check, paid, only on the user's go-ahead: `TestLLMGenText` on `claude-4.5-haiku` via `bedrock` with `AWS_BEARER_TOKEN_BEDROCK` set, which failed all its cases in the evidence run. Not run under the goal that executed this plan, which gave no go-ahead for paid inference; the offline wire tests stand in for it.
+- [x] `/rev`, two rounds at profile 3. The first made the docs say that `bedrock_token` still takes its region from `AWS_REGION` or the AWS profile, and made the missing-keys hint say that under `secret_provider` the `bedrock_token` variant reads the token from the secrets provider. The second gave the hint its own sentence, made the subclass forward the constructor options it does not name (anthropic 0.108 passes `middleware` through `copy`), and moved the `landed` flip into the pull request.
+- [x] PR `fix/Bedrock-bearer-token-env · L-260927-06f4db`, body ending `Closes L-260927-06f4db`. `/ledger-land` does not flip a document in a code repo's `wip/`, so this document and `design.md` say `landed` from the pull request's last commit.