WIF reference

This page collects the configuration surfaces, validation constraints, and error mappings for Workload Identity Federation (WIF). For setup walkthroughs, see Identity providers.

Token exchange request

POST /v1/oauth/token accepts a JSON body using the RFC 7523 jwt-bearer grant. The SDK builds this request for you from the environment variables.

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. The SDK also reads ANTHROPIC_WORKSPACE_ID, but this path activates with or without it.

Credential precedence

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

In the ant CLI, the settings for Claude Models on Google Cloud (Anthropic managed) rank after the federation environment variables and before the active profile. The settings are the project, the workspace ID, and the location. You set them with the --google-cloud-* flags or the ANTHROPIC_GOOGLE_CLOUD_* variables. The CLI uses these settings when any one of them is set. With these settings, the CLI gets its credential from Google Application Default Credentials.

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, such as "1.0". The SDK writes this field automatically. If you omit it when authoring a config by hand, 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 you omit authentication.identity_token, 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 (by resource, or read versus write) are not 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 a rule can grant. 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 it verifies 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

Anthropic validates the issuer_url, jwks.discovery_base, and jwks.url fields:

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 Anthropic accepts an incoming JWT. The JWT must satisfy every populated matcher. Set at least one of subject_prefix, claims, or condition. Anthropic rejects a match block that contains only audience or no matchers at all. 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 reports an exchange failure as WorkloadIdentityError, which gives the HTTP status and the error details from the response body. Except in C# and PHP, the SDK also gives the request ID: on the error, in the exception’s response headers, or in the error’s message.

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 authentication history in the Claude Console records the deny reason on the attempt’s entry. For example, it shows 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 confirmed (the 400 invalid_request_error family in the previous table) leave no history entry. Their response messages name the problem directly. A 401 with no matching history entry usually means that Anthropic did not recognize the federation_rule_id.

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 appears 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. A workload that resends the same JWT (a retry loop, or a refresh that rereads an unrotated token) fails on the second exchange. The authentication history page shows these attempts with the reason jti_reused. To fix this, mint a fresh assertion for each exchange.

If you 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:

   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. The comparison is case-sensitive. A trailing * makes it a prefix match, and 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, Anthropic rejects an otherwise valid token.

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. Its type field selects the source mode:

Each type takes its own companion fields, so those fields are mutually exclusive. 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. After your identity provider publishes a new signing key, exchanges of tokens signed with it might 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. Keep the replaced key in the JWKS until the tokens it signed have expired. Managed identity providers typically do this on their own. If you operate your own issuer, confirm that your rotation policy publishes new keys ahead of first use. Examples are a self-managed Kubernetes cluster, a SPIRE OIDC discovery provider, and an Okta custom authorization server with a configured rotation schedule.