Skip to content

Workload Identity Federation for Agent Runtimes

Replace long-lived API keys with short-lived tokens minted from the runtime's existing workload identity — making the federation trust rule a security boundary.

Learn it hands-on: Keys That Expire in Minutes — guided lesson with quizzes.

A static sk-ant-... API key is the highest-blast-radius credential on an agent runtime — leakable from logs, hooks, and transcripts, with rotation cadences that never match incident timelines. Workload Identity Federation (WIF) removes the key: the workload presents a signed OIDC JWT from an identity provider it already runs inside, and Anthropic mints a short-lived access token bound to a service account. [Source]

The federation contract

Three resources express the trust contract:

Resource Anthropic ID Role
Federation issuer fdis_... Registers an OIDC provider URL plus a JWKS source (discovery, explicit URL, or inline keys)
Service account svac_... The non-human identity the minted token acts as; lives at the org and joins workspaces
Federation rule fdrl_... "When a JWT from issuer X has claims that look like Y, mint a token for service account Z with scope S"

The workload presents its IdP-issued JWT to POST /v1/oauth/token using the RFC 7523 jwt-bearer grant, citing the rule ID. Anthropic verifies the signature against the registered JWKS, matches claims against the rule, and returns an sk-ant-oat01-... token scoped to the matched service account and workspace. [Source]

sequenceDiagram
    participant Workload
    participant IdP as Identity Provider
    participant Anthropic
    Workload->>IdP: Request identity token (ambient)
    IdP-->>Workload: Signed JWT (iss, sub, aud, exp)
    Workload->>Anthropic: POST /v1/oauth/token (assertion=JWT, rule_id, ...)
    Anthropic->>IdP: Fetch JWKS (or use inline keys)
    Anthropic->>Anthropic: Match JWT claims against rule
    Anthropic-->>Workload: sk-ant-oat01-... + expires_in
    Workload->>Anthropic: API request (Authorization: Bearer)

The five environment variables

The Anthropic SDKs read these and run the exchange with no constructor arguments. Ship one container image, then inject federation parameters per environment. [Source]

Variable Required Role
ANTHROPIC_FEDERATION_RULE_ID Yes fdrl_... ID of the rule to evaluate
ANTHROPIC_ORGANIZATION_ID Yes UUID of your Anthropic organization
ANTHROPIC_SERVICE_ACCOUNT_ID Yes svac_... ID of the target service account
ANTHROPIC_IDENTITY_TOKEN_FILE One of _TOKEN_FILE or _TOKEN Path to the JWT; re-read on every refresh so rotated projected tokens are picked up
ANTHROPIC_WORKSPACE_ID Conditional wrkspc_... ID; required when the rule covers more than one workspace. Added in Claude Code v2.1.141 (2026-05-13) as the per-exchange workspace scoping signal

[Source: Claude Code changelog]

Scoping pitfalls that widen access

WIF replaces secret sprawl with a trust-policy design problem. The rule deciding which JWTs may act as a service account is now part of the threat model. Four pitfalls recur.

Broad subject_prefix matches more than intended. On GitHub Actions, repo:your-org/* matches every repo and, without a ref constraint, accepts pull_request runs from forks. Any external contributor opening a PR can obtain a federated token. Pin to a single repository and protected branch, and add repository_owner under claims as defense in depth. [Source]

A missing audience widens to default tokens. On Kubernetes, system:serviceaccount:* matches every pod. Without an audience matcher the rule also accepts the default-audience tokens every pod has projected. Set audience on both the rule and the pod's serviceAccountToken projection. [Source]

CEL conditions are now a security boundary. Anthropic supports a CEL expression for complex claim logic, but warns: "an expression that evaluates to true for more inputs than intended grants broader access than intended. Prefer the static matchers when they express your constraint." [Source]

API keys silently shadow federation during migration. ANTHROPIC_API_KEY outranks the federation env vars. A leftover key in CI secrets, container env, or shell profile means the workload still authenticates statically. Worse, ANTHROPIC_API_KEY="" still wins. Unset it, do not blank it. Confirm with ant auth status. [Source]

Token lifetime bounds blast radius

The minted token's lifetime is min(rule.token_lifetime_seconds, 2 × JWT_remaining) with a 60-second floor; default 3600s. The second bound prevents the Anthropic token from outliving the upstream identity. The SDK refreshes at exp − 120s (advisory) and exp − 30s (mandatory). [Source]

A leaked sk-ant-oat01-... expires in minutes; a leaked static key works until manual rotation, from any network the attacker controls.

When federation is not worth the complexity

WIF is qualified, not unconditional. A small team on a single fixed host can match the blast-radius reduction with vault-rotated keys via a wrapper script (Scoped Credentials via Proxy). Federation adds three resources and a trust policy an unfamiliar team can mis-scope into a worse posture than a well-rotated key. It earns its complexity when the runtime already has an ambient workload identity (Kubernetes service account, AWS IRSA, GitHub Actions OIDC) shared across multiple workloads.

WIF also does not close the workload attestation gap. Token exchange verifies the JWT signature and matches its claims, but does not attest that the workload presenting the token is the one it claims to be. That must be solved at the IdP layer, which most organizations have not done. A service account scoped too broadly means WIF "will faithfully mint a valid Anthropic token for the wrong workload." Treat WIF as authentication for one destination, not a substitute for an attested workload-identity program. [Source: Aembit]

Key Takeaways

  • Static sk-ant-... API keys are the highest-blast-radius credential on an agent runtime; federation replaces them with tokens that expire in minutes.
  • The trust contract is three resources (issuer, service account, rule); the rule's match block is now itself a security boundary.
  • ANTHROPIC_WORKSPACE_ID is required only when the federation rule covers more than one workspace — added in Claude Code v2.1.141 to make per-exchange workspace scoping explicit.
  • Pin subject_prefix narrowly, always set audience, prefer static matchers over CEL, and unset (do not blank) ANTHROPIC_API_KEY before declaring migration complete.
  • Token lifetime is capped at 2 × JWT_remaining, so a leaked federated token cannot outlive the upstream workload identity it was derived from.
Established — multiple independent sources Last reviewed: 2026-06-03
Feedback