claude-code - 💡(How to fix) Fix [DOCS] Bedrock `awsCredentialExport` docs omit always-run behavior for cross-account auth [1 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/amazon-bedrock

Section/Topic

Advanced credential configuration, especially the awsCredentialExport explanation

Current Documentation

The Bedrock page currently says:

When Claude Code detects that your AWS credentials are expired (either locally based on their timestamp or when Bedrock returns a credential error), it will automatically run your configured awsAuthRefresh and/or awsCredentialExport commands to obtain new credentials before retrying the request.

awsCredentialExport: Only use this if you can't modify .aws and must directly return credentials. Output is captured silently and not shown to the user.

The settings reference also currently says:

awsCredentialExport | Custom script that outputs JSON with AWS credentials (see advanced credential configuration)

What's Wrong or Missing?

These docs still describe awsCredentialExport as a helper Claude Code runs only after credentials are expired or Bedrock returns a credential error.

That is outdated for the v2.1.141 behavior change: when awsCredentialExport is configured, Claude Code now always runs it instead of skipping it when ambient AWS credentials already resolve. Without documenting that precedence, Bedrock users who rely on exported credentials for cross-account access can reasonably assume Claude Code will keep using ambient credentials until they expire, which does not match the current behavior.

The current wording also does not explain why someone would choose awsCredentialExport over ambient credentials or awsAuthRefresh for cross-account Bedrock authentication.

Suggested Improvement

Update the Bedrock page so awsCredentialExport documents its current precedence and intended use case.

Before:

When Claude Code detects that your AWS credentials are expired ... it will automatically run your configured awsAuthRefresh and/or awsCredentialExport commands ... before retrying the request.

After:

awsAuthRefresh runs when Claude Code needs to refresh credentials stored in .aws.

If awsCredentialExport is configured, Claude Code always runs it to obtain request credentials, even when ambient AWS credentials already resolve. Use this when Claude Code must assume or export a different credential set than the ambient AWS SDK chain provides, such as cross-account Bedrock access.

Also add a short note in the settings reference entry for awsCredentialExport that points back to this always-run cross-account behavior.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

Total scope: 2 pages affected

Version context: This gap is about the Bedrock authentication behavior documented after v2.1.141.