Workload Identity Federation



Federation issuers

A federation issuer (fdis_...) registers an OIDC identity provider with your organization. Registering an issuer tells Anthropic "JWTs signed by this provider may assert workload identity for my org."

An issuer has two pieces of configuration:

• Issuer URL: The exact iss claim value that appears in the provider's JWTs, for example https://token.actions.githubusercontent.com or https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLE.
• JWKS source: How Anthropic fetches the public keys to verify JWT signatures. Use discovery (the default) for any provider that serves /.well-known/openid-configuration at its issuer URL. Use explicit_url to point at a JWKS endpoint directly, or inline to upload the key set for issuers that are not reachable from the public internet (for example, a private Kubernetes cluster).

Issuer and JWKS URLs must be https, on port 443, and use a public DNS host name that resolves to public IP addresses; IP literals are not accepted. These constraints apply only to URLs Anthropic fetches; in explicit_url and inline modes the issuer_url is compared as a string and may reference an internal hostname.

You typically register one issuer per environment: your production EKS cluster, your staging cluster, and GitHub Actions are three separate issuers.



Federation rules

A federation rule (fdrl_...) is the bridge between an issuer and a service account: "when a JWT from issuer X has claims that look like Y, mint a token for service account Z with scope S."

A rule defines match conditions, a target, and the authorization scope and token lifetime that apply when the rule matches:

• Match: The conditions an incoming JWT must satisfy. You can match on a subject_prefix (for example, system:serviceaccount:prod:worker, or with a trailing * for a prefix match), an exact audience, a map of exact claim values, a CEL condition expression for complex logic, or any combination. At least one of subject_prefix, claims, or condition must be set, and all configured matchers must pass for the JWT to be accepted.
• Target: The service account the matched JWT maps to.
• Authorization: The OAuth scope granted on the minted token. The default is workspace:developer, which grants the same access as an API key issued for that workspace. Some products lock the scope when you create a rule from their flow; for example, the MCP tunnels create-tunnel modal creates rules scoped to org:manage_tunnels. See OAuth scopes. The rule also sets token_lifetime_seconds (60 to 86400, default 3600).

A single issuer can have many rules: one per team, namespace, or permission level. Rules are evaluated by ID: the client specifies which rule to use in the exchange request, and Anthropic verifies the JWT satisfies that rule's match criteria. There is no implicit rule search.



How it works

1. Your IdP issues a JWT to the workload. On most platforms this is ambient: a Kubernetes projected service-account token, the Google Cloud metadata server, Azure IMDS, or the GitHub Actions OIDC endpoint. The JWT's iss claim identifies the provider, and its sub and other claims identify the specific workload.
2. The SDK exchanges the JWT for an Anthropic access token. The SDK posts the JWT to POST /v1/oauth/token using the RFC 7523 jwt-bearer grant. Anthropic verifies the JWT against the issuer's JWKS and the federation rule's match conditions, then returns a short-lived sk-ant-oat01-... token that acts on behalf of the rule's target service account.
3. The SDK sends the token on every request and refreshes it before it expires. Your application code constructs the client with no api_key and calls the API as usual. The SDK re-runs the exchange before the token expires.



Set up federation

You need the admin, owner, or primary owner role in your Anthropic organization, an OIDC-capable identity provider with a reachable JWKS endpoint (or a JWKS document you can paste, for air-gapped clusters), and a workload that can obtain an identity token from that provider.

The Connect workload wizard creates all three resources (the issuer, the service account, and the federation rule) in one guided flow, then verifies the connection end to end.

To manage these resources programmatically, see Manage WIF with the Admin API.



Authenticate from your workload

With federation configured, your workload exchanges its IdP-issued JWT for an Anthropic token at runtime. The SDKs handle the exchange and refresh loop for you. The cURL tab shows the underlying HTTP exchange for shell scripts, debugging, or languages without SDK support.



Construct the SDK client

You can construct the client with explicit credentials or with no arguments. With no arguments, the SDK resolves credentials from environment variables or the active profile, as described under Credential precedence. The zero-argument form is the recommended pattern for production workloads: ship the same container image everywhere and inject ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID, and ANTHROPIC_IDENTITY_TOKEN_FILE per environment.

The token-exchange response follows RFC 6749 §5.1. See Token exchange response for the field reference.



Credential precedence

Every SDK resolves credentials in the same five-tier order: constructor arguments, then ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN, then an explicit ANTHROPIC_PROFILE, then the federation environment variables, then the implicit active profile. The first source that yields a credential wins.

For the full precedence table, the per-tier semantics, and the profile file schema, see Credential precedence in the WIF reference.



Migrate from API keys

To switch an existing workload from a static API key to federation without downtime:

1. Configure federation in parallel. Complete the setup walkthrough and confirm the federation rule matches your workload's token. Leave the existing ANTHROPIC_API_KEY in place for now.
2. Smoke-test which credential wins. Run ant auth status from inside the workload (or inspect SDK debug logs). Because ANTHROPIC_API_KEY sits above the federation tiers in the precedence chain, the API key still wins at this stage.
3. Unset ANTHROPIC_API_KEY everywhere it is injected. Remove it from CI secrets, container environment, and shell profiles (see the preceding warning). Re-run ant auth status and confirm the federation source is now selected.
4. Revoke the API key. Once the workload is running on the federated token, delete the key in the Claude Console under Settings → API keys.



Token lifetime and refresh

The minted Anthropic token's lifetime is the lesser of (a) the rule's token_lifetime_seconds (default 3600 seconds) and (b) twice the remaining lifetime of the IdP JWT you presented. The result is never less than 60 seconds. The second bound prevents an Anthropic token from outliving the upstream identity it was derived from by more than a small margin.

The SDKs cache the token and refresh it on a two-tier schedule modeled on botocore:

• Advisory refresh at expiry minus 120 seconds. The SDK attempts a new exchange. If the token endpoint is unreachable, the SDK continues serving the cached token, which is still valid for roughly 90 more seconds.
• Mandatory refresh at expiry minus 30 seconds. A failed exchange at this point raises an error. The cached token is too close to expiry to be safe.

Because the SDK re-reads ANTHROPIC_IDENTITY_TOKEN_FILE on every exchange, it transparently picks up rotated projected tokens (Kubernetes service-account tokens, for example, rotate well before their exp).



Identity providers

Each guide covers where the JWT comes from on that platform, what its claims look like, and the issuer and rule configuration to register.



See also

• Manage WIF with the Admin API: create issuers, service accounts, and rules from infrastructure as code
• WIF reference: environment variables, profile file schema, validation rules, and error codes
• Authentication: all authentication options across the Anthropic SDKs
• Admin API reference: generated request and response schemas for every Admin API endpoint