Skip to content
← Back to release · 2.1.318
New features / v2.1.318

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_role with session_name on every bedrock and mantle upstream except those that use aws_bearer_token. Those can't take assume_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

Change details