Add assume_role on gateway upstreams
CHANGELOG · original
Added assume_role on mantle upstreams of the Claude apps gateway, for a role in another AWS account and for per-developer AWS cost attribution Open official changelog ↗ Documentation
Documentation excerpt
Per-developer AWS cost attribution
By default the gateway signs every Bedrock request with one credential, so AWS sees all developers' requests under a single IAM principal. Add session_name: email to assume_role and the gateway calls sts:AssumeRole once per developer per hour, with the session name set to that developer's email, and signs their requests with the returned credentials, so each developer's requests reach AWS under their own assumed-role session. The role can be in the gateway's own account.
Requires a gateway running Claude Code v2.1.281 or later. Cost attribution on AWS covers the IAM role and where AWS billing shows the sessions.
[!NOTE]
For per-developer attribution, set
assume_rolewithsession_nameon everybedrockandmantleupstream except those that useaws_bearer_token. Those can't takeassume_role, so their requests stay under one principal.
upstreams:
- provider: bedrock
region: us-east-1
auth: {} # the gateway's own role: it only calls STS
assume_role:
role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user
session_name: email # or sub
session_name selects which verified claim becomes the AWS RoleSessionName: email or sub. The gateway writes any character other than ASCII letters, digits, and _+,.@- as =XX hex per UTF-8 byte, and shortens a result longer than 64 characters to a prefix plus a hash, so each developer's session name stays valid and unique. A request from a developer whose token lacks the claim isn't sent through this upstream, and the operator log says to switch to sub or set oidc.email_claim.
An active developer costs one STS call per hour per gateway replica, and concurrent first requests share one call.
The gateway also makes one call of its own on this role: the token count for a request the client abandoned, so that spend limits stay accurate. That count and its one-token fallback request are signed by the shared claude-apps-gateway session, so AWS attributes the fallback to claude-apps-gateway rather than to the developer.
Documentation snapshot · 2026-11-20