feat(bedrock): support Amazon Bedrock API key (bearer token) authentication

[Winne004]

Is your feature request related to a problem? Please describe.

The Bedrock provider currently offers no way to authenticate with an Amazon Bedrock API key (bearer token). Bedrock API keys let you call the service with a bearer token instead of SigV4-signed AWS credentials, and come in two flavors:

• Short-term – lasts up to 12 hours (or the duration of your session, whichever is shorter), inherits permissions from the IAM principal that generated it. Recommended for production.
• Long-term – lasts until a configured expiration date, backed by an auto-created IAM user. Recommended only for exploration.

Today, _build_bedrock in instructor/v2/auto_client.py explicitly ignores the api_key argument and only wires up classic credential parameters:

https://github.com/567-labs/instructor/blob/main/instructor/v2/auto_client.py

def _build_bedrock(
    *,
    provider: str,
    model_name: str,
    async_client: bool,
    mode: Mode | None,
    api_key: str | None,  # noqa: ARG001   <-- silently ignored
    kwargs: dict[str, Any],
    ...
) -> InstructorType:
    ...
    for key in [
        "aws_access_key_id",
        "aws_secret_access_key",
        "aws_session_token",
    ]:
        ...

So this silently falls back to the default credential chain instead of using the key:

client = instructor.from_provider(
    "bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0",
    api_key="bedrock-api-key-...",  # ignored, no warning
)

This hurts ergonomics for people trying out instructor with Bedrock: every other major provider (openai/..., anthropic/..., etc.) works with a single api_key, while Bedrock forces users to set up the full AWS credential chain even though the service itself now supports simple bearer-token auth.

Describe the solution you'd like

Support Bedrock API keys in the Bedrock provider path:

1. In _build_bedrock, when api_key is passed (or AWS_BEARER_TOKEN_BEDROCK is set in the environment), configure the boto3 client to use bearer-token auth instead of SigV4 credentials. botocore natively supports this since boto3 1.39.0 via the AWS_BEARER_TOKEN_BEDROCK environment variable, so a minimal implementation could be:

   if api_key:
       os.environ["AWS_BEARER_TOKEN_BEDROCK"] = api_key

   (or, more hygienically, by injecting the token into the botocore session/auth config rather than mutating os.environ).

2. Document the option in the Bedrock integration docs, including the AWS_BEARER_TOKEN_BEDROCK environment variable, so users know both paths exist.

3. If bearer auth can't be honored (e.g. boto3 too old), raise or warn instead of silently ignoring api_key.

Describe alternatives you've considered

• Setting AWS_BEARER_TOKEN_BEDROCK manually before creating the client — this works because botocore picks it up, but it is undocumented in instructor and doesn't help users who reach for the api_key parameter that every other provider accepts.
• Building a boto3 client myself and using instructor.from_bedrock(client) — works, but defeats the purpose of the from_provider one-liner.
• At minimum, a warning when api_key is passed to from_provider("bedrock/...") would prevent silent misconfiguration.

Additional context

• AWS announcement: https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/
• Bedrock API key docs: https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys.html
• boto3 support for AWS_BEARER_TOKEN_BEDROCK landed in 1.39.0 (July 2025).

Happy to submit a PR for this if the approach above sounds reasonable.

[jxnl]

1.16 triage: keeping this valid authentication request open with PR #2409. The current patch mutates AWS_BEARER_TOKEN_BEDROCK process-wide, which is unsafe for concurrent clients; AWS documents the environment-variable path, but library-level api_key= support needs a session-scoped botocore mechanism and live Bedrock proof before merge.

[Winne004]

Yeah, you're right, the os.environ write was lazy of me. It's worse than just concurrency too, it persists after the client is built and leaks into every other client in the process, Bedrock or not. Let me fix it properly.

botocore actually gives us a clean per-client hook for this. The Bedrock bearer token gets resolved through the session's token_provider component, and the default provider reads from an environ dict that just happens to default to os.environ. But you can hand it your own dict, so nothing global gets touched:

import boto3
from botocore.tokens import ScopedEnvTokenProvider, SSOTokenProvider, TokenProviderChain

boto_session = boto3.session.Session()
botocore_session = boto_session._session
botocore_session.register_component(
    "token_provider",
    TokenProviderChain(providers=[
        ScopedEnvTokenProvider(botocore_session, environ={"AWS_BEARER_TOKEN_BEDROCK": api_key}),
        SSOTokenProvider(botocore_session),
    ]),
)
client = boto_session.client("bedrock-runtime", **aws_kwargs)

The token gets baked into the client's request signer at construction, so it's scoped to that one client and there's no shared state. I checked this against botocore 1.43.71: the client's signer ends up holding the key, os.environ stays clean, and a plain Session() built right next to it resolves None. So two clients with different keys can coexist, which was the whole problem.

If no api_key is passed I don't register anything, so a user-exported AWS_BEARER_TOKEN_BEDROCK and the normal SigV4 chain behave exactly as before.

The catch, and I want to be upfront about it: ScopedEnvTokenProvider/TokenProviderChain and boto3.Session._session are botocore internals. register_component itself is the sanctioned extension point, but those classes aren't a public contract. So I'll pin boto3>=1.39.0 and guard the import, if the resolver classes aren't there we raise/warn instead of silently dropping the key like the old code did.

On the live proof, that's fair, I'll run a real Bedrock call with a short-term key and attach it, plus a negative case showing a bad key comes back 403 instead of quietly falling through to SigV4. The wiring tests stay deterministic; the live call is the actual merge gate.

Want this pushed onto #2409 or as a separate commit so the diff's easier to read?