WIF reference

This page collects the configuration surfaces, validation constraints, and error mappings for Workload Identity Federation. For setup walkthroughs, see the provider guides.

Token exchange request

POST /v1/oauth/token accepts a JSON body using the RFC 7523 jwt-bearer grant. The SDKs build this request for you from the environment variables; the cURL examples on each provider guide show the raw body.

Token exchange response

POST /v1/oauth/token returns a standard OAuth 2.0 token response (RFC 6749 §5.1):

Environment variables

The SDK reads these variables to perform a federated token exchange with no constructor arguments.

The direct environment-variable federation path activates only when ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, and one of ANTHROPIC_IDENTITY_TOKEN_FILE or ANTHROPIC_IDENTITY_TOKEN are all set. ANTHROPIC_WORKSPACE_ID is read alongside but does not gate activation.

Credential precedence

The SDK resolves credentials in this order. The first source that yields a credential wins.

When a profile is loaded, environment variables fill any fields the profile omits but never override fields the profile sets explicitly. For example, ANTHROPIC_WORKSPACE_ID fills workspace_id only when the active profile does not set it.

Profile configuration file

A profile is a named configuration file that the SDK and the ant CLI both read. Profiles let you ship federation parameters with your container image or switch between environments without changing code.

Configuration directory

The SDK locates the configuration directory in this order:

1. $ANTHROPIC_CONFIG_DIR
2. ~/.config/anthropic on Linux and macOS
3. %APPDATA%\Anthropic on Windows

Active profile

The active profile name resolves in this order:

1. $ANTHROPIC_PROFILE
2. The contents of <config_dir>/active_config (a one-line file written by ant profile activate <name>)
3. The literal name default

Claude Code and the Claude Agent SDK honor this same resolution order, so a federation profile configured here also authenticates those tools without additional setup.

File layout

Both the config file and the credentials file carry a top-level string version field in major.minor format (currently "1.0"). The SDK writes this field automatically so future releases can detect and migrate older formats; omit it when authoring a config by hand and the SDK treats the file as the current version.

Federation profile example

{
  "version": "1.0",
  "authentication": {
    "type": "oidc_federation",
    "federation_rule_id": "fdrl_...",
    "service_account_id": "svac_...",
    "identity_token": {
      "source": "file",
      "path": "/var/run/secrets/anthropic.com/token"
    }
  },
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "wrkspc_...",
  "base_url": "https://api.anthropic.com"
}

If authentication.identity_token is omitted, the SDK falls back to ANTHROPIC_IDENTITY_TOKEN_FILE or ANTHROPIC_IDENTITY_TOKEN from the environment.

OAuth scopes

The oauth_scope you set on a federation rule determines which Claude API endpoints the minted access token can call.

A request to an endpoint outside the token's scope returns HTTP 403. Finer-grained scopes (per resource, or read versus write) are not currently available.

Permission boundaries

A federation rule's oauth_scope is a ceiling: the minted token can never exceed it. The target service account's organization_role (developer or admin) determines which scopes are grantable, so a rule that grants org:admin must target a service account with organization_role=admin. Effective permissions are the intersection of the rule's scope and the service account's role.

Validation rules

Anthropic enforces these constraints when you create or update issuers and rules, and when verifying an incoming JWT at exchange time.

For complete parameter details and response schemas, see the Service accounts API reference, Federation issuers API reference, and Federation rules API reference.

Resource fields

URL fields

The issuer_url, jwks.discovery_base, and jwks.url fields are validated:

URL validation failures return 400 invalid_request_error with the field name as a prefix on the error message (for example, issuer_url: url must use https scheme).

JWT verification

Rule matching semantics

A federation rule's match block determines whether an incoming JWT is accepted. All populated fields are evaluated with AND semantics: the JWT must satisfy every populated matcher. At least one of subject_prefix, claims, or condition must be set; a match block that contains only audience (or no matchers at all) is rejected. This guards against rules that would accept every token from an issuer.

CEL evaluation environment

The condition expression has access to a single variable:

Example:

claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]

Errors

Token exchange errors

POST /v1/oauth/token returns errors in the standard API error shape. The SDK wraps exchange failures in a typed FederationExchangeError (or language equivalent) that exposes the HTTP status, the response body, and the request_id.

Every assertion denial returns the same opaque 401 authentication_error with the fixed message Authentication failed, regardless of which check failed; a distinguishable error would let a caller probe rule configuration. The deny reason is recorded on the attempt's entry in the authentication history, for example match_subject_prefix when the sub claim fails the rule's subject_prefix, or workspace_id_required when the rule spans multiple workspaces and the request names none. Requests rejected before the rule's organization is corroborated (the 400 invalid_request_error family above) leave no history entry; their response messages name the problem directly. A 401 with no matching history entry usually means the federation_rule_id itself was not recognized.

Common SDK-side failures

Troubleshoot a failed exchange

A 401 authentication_error response is intentionally opaque and its message is always Authentication failed; the deny reason is recorded in the authentication history, not in the response.

One common opaque failure is a replayed assertion: an assertion that carries a jti claim can be exchanged only once, so a workload that re-sends the same JWT (a retry loop, or a refresh that re-reads an unrotated token) is rejected on the second exchange. The authentication history page shows these attempts with the reason jti_reused; the fix is to mint a fresh assertion for each exchange.

If you still need to debug from the JWT itself, work through these checks in order:

1. 1

   Decode the JWT

   Decode the assertion you sent so you can compare each claim against your issuer and rule configuration:

   cURL

   

   jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"

2. 2

   Check iss matches the issuer

   The decoded iss claim must equal the registered issuer_url byte for byte, including scheme, port, and any trailing slash. A mismatch on a single character fails verification.

3. 3

   Check aud matches the rule

   The decoded aud claim must contain the rule's audience value as an exact match. When aud is an array, one element must match exactly.

4. 4

   Check sub and each claims entry

   Compare sub against the rule's subject_prefix (case-sensitive; a trailing * is a prefix match, anything else is exact). Compare every key in the rule's claims map against the same-named top-level claim.

5. 5

   Check exp, nbf, and iat

   exp must be in the future and nbf/iat must be in the past, within the 30-second skew window. If the workload host's clock has drifted, an otherwise valid token is rejected.

6. 6

   Check JWKS reachability

   For discovery mode, fetch <jwks.discovery_base or issuer_url>/.well-known/openid-configuration over public HTTPS on port 443 and confirm jwks_uri resolves. For explicit_url, fetch the JWKS URL directly. For inline, confirm the issuer's signing key has not rotated since you registered the keys.

   If the issuer rotated its signing key and immediately started signing with it, exchanges can fail for up to a minute while Anthropic's JWKS cache refreshes. See Key rotation and caching.

JWKS source modes

When you register a federation issuer, the jwks field controls how Anthropic obtains the public keys used to verify JWT signatures from that issuer. It is a discriminated union keyed on type:

The discriminated union makes the companion fields mutually exclusive by construction. Both discovery and explicit_url also accept an optional ca_cert_pem string for issuers that serve TLS from a private CA.

Key rotation and caching

In discovery and explicit_url modes, Anthropic caches the fetched JWKS. If your identity provider publishes a new signing key and immediately starts signing tokens with it, exchanges that present those tokens may fail with a signature error for up to 1 minute while the cache refreshes.

To avoid this window, publish a new signing key in the JWKS at least 15 minutes before your identity provider starts signing tokens with it, and keep the superseded key in the JWKS until tokens it signed have expired. Managed identity providers typically follow this discipline on their own. If you operate your own issuer (a self-managed Kubernetes cluster, a SPIRE OIDC discovery provider, or an Okta custom authorization server with a configured rotation cadence), confirm that your rotation policy publishes new keys ahead of first use.