What you will be able to do
- Explain how a service account, a federation issuer and a federation rule together let a workload authenticate without a static key
- Trace a federated token exchange from IdP-issued JWT to a short-lived sk-ant-oat01 token
- Predict which credential the SDK uses when several are present in the environment
1.Replacing static keys with federated identity
Production workloads on AWS, Google Cloud, Azure, Kubernetes or CI already have an identity issued by their platform. Workload Identity Federation (WIF) lets them use that identity with the Claude API. The workload presents a signed OIDC JWT from its identity provider, and Anthropic returns a short-lived access token bound to a service account. Nobody mints, distributes or rotates an sk-ant-api... string, so there is nothing long-lived to leak. Federated tokens give the same access to Claude API endpoints as API keys. What changes is how long a stolen credential stays useful: minutes, not forever.
Three Console resources set up the trust. Read together, they say that tokens signed by issuer X, with claims that look like Y, may act as service account Z:
- A service account (svac_...) is a non-human identity with no email, password or Console login. It is implicitly a member of the default workspace, and you add it to any other workspace it needs.
- A federation issuer (fdis_...) registers an OIDC provider by its exact iss value and a JWKS source for checking signatures. Teams usually register one issuer per environment.
- A federation rule (fdrl_...) links the two. It sets the match conditions (subject_prefix, audience, exact claims or a CEL expression, of which at least one must be set), the target service account, an OAuth scope (default workspace:developer) and token_lifetime_seconds between 60 and 86400.
Access approval happens in the rule. All of the rule's matchers have to pass. The client names the rule by ID in each exchange, and Anthropic never searches for some other rule that might match. Setting all of this up requires the admin, owner or primary owner role. Auditing is also easier: a workspace key is a credential, while a service account *has* credentials, so you can see which workload acted as which identity.
Checkpoint 1 of 4· Match them up
Match each federation resource to its role.
Tap a term, then the definition that fits it.
The issuer decides whose signatures count, the rule decides which claims qualify and what scope they get, and the service account is the identity the resulting token acts as.
“A federation rule (fdrl_...) is the bridge between an issuer and a service account”Source: platform.claude.com
2.How a workload exchanges its JWT for a Claude token
The workload usually gets its JWT from the platform without asking for it: a Kubernetes projected service-account token, the Google Cloud metadata server, Azure IMDS or the GitHub Actions OIDC endpoint. The SDK posts that JWT to POST /v1/oauth/token using the RFC 7523 jwt-bearer grant, along with the rule ID, organization ID and service account ID. Anthropic checks the signature against the issuer's JWKS and checks the claims against the rule. If both pass, it returns an sk-ant-oat01-... bearer token. The SDK sends that token on each request and runs the exchange again before the token expires.
from anthropic import Anthropic, WorkloadIdentityCredentials, IdentityTokenFile
client = Anthropic(
credentials=WorkloadIdentityCredentials(
identity_token_provider=IdentityTokenFile(
"/var/run/secrets/anthropic.com/token"
),
federation_rule_id="fdrl_...",
organization_id="00000000-0000-0000-0000-000000000000",
service_account_id="svac_...",
workspace_id="wrkspc_...",
),
)In production, the recommended form passes no arguments at all. Ship one container image and set ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID and ANTHROPIC_IDENTITY_TOKEN_FILE per environment. The SDK re-reads the token file on every exchange, so a projected token that rotates on disk is always current. The workspace is chosen at exchange time and must be one the service account belongs to. Moving to another workspace takes a new exchange, not a header.
Checkpoint 2 of 4· Check yourself
A federation rule is enabled for exactly one workspace, and the workload leaves out workspace_id in the token exchange. What happens?
workspace_id is only required when the rule covers more than one workspace. When it's left out, the server uses the rule's only enabled workspace.
“When omitted, the server selects the rule's sole enabled workspace.”Source: platform.claude.com
3.Which credential the SDK actually uses
The SDK checks credential sources in a fixed order and uses the first one that yields a credential. It doesn't merge sources or warn about conflicts. Credentials left over from an earlier setup therefore quietly decide which identity your requests run as.
| Order | Source | What to know |
|---|---|---|
| 1 | Constructor argument (api_key=, auth_token=, credentials=) | Always overrides everything else |
| 2 | ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN | Shadows federation entirely; unset when migrating |
| 3 | ANTHROPIC_PROFILE | Loads the named profile; a missing named profile is an error, not a fall-through |
| 4 | Federation environment variables | Need rule ID, organization ID, service account ID and an identity token or token file |
| 5 | Active profile | From active_config, falling back to a profile named default |
Two details trip up migrations. The federation path at step 4 turns on only when all four required variables are present. ANTHROPIC_WORKSPACE_ID is read too, but it doesn't count toward that check, so a missing service account ID makes the SDK skip federation silently. Profiles and environment variables also combine: once a profile is loaded, environment variables fill only the fields the profile leaves out and never override a field the profile sets.
Checkpoint 3 of 4· Check yourself
A pod sets ANTHROPIC_PROFILE=staging-profile, but no file by that name exists in the config directory. Valid federation variables are also set. What does the SDK do?
A named profile that's missing stops resolution with an error. The SDK doesn't go on to the lower-priority sources.
“A missing named profile is an error, not a fall-through.”Source: platform.claude.com
Checkpoint 4 of 4· Exam question
A platform team configures a federation rule with `subject_prefix` set to `system:serviceaccount:prod:worker` and no `claims` or `condition` matchers. A JWT arrives from the cluster with `sub` equal to `system:serviceaccount:staging:worker-2`. Will this JWT be accepted by the rule, and why?
Correct answer: A — No, because the subject does not start with `system:serviceaccount:prod:worker`; the `staging` namespace fails the prefix match even though the trailing segment is similar.
- A. Correct. subject_prefix performs a literal prefix match on the sub claim; `system:serviceaccount:staging:worker-2` does not start with `system:serviceaccount:prod:worker`, so the match fails and the token exchange is denied.
- B. Incorrect. subject_prefix is a literal string prefix check, not a set-membership or reordering check across segments.
- C. Incorrect. There is no automatic fallback to audience matching; unset matchers simply are not evaluated, and the configured subject_prefix still applies and fails.
- D. Incorrect. A rule is valid with just one of subject_prefix, claims, or condition set; at least one, not at least two, is required.
Sources3
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Once the federation environment variables are configured, the SDK prefers them over an existing ANTHROPIC_API_KEY.Why is that wrong?
ANTHROPIC_API_KEY is checked first and wins. Federation runs only after that variable is unset.
Covered in Which credential the SDK actually uses
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“There are no static secrets to mint, store in CI, rotate, or leak.”
↩︎ Replacing static keys with federated identity“tokens signed by issuer X, with claims that look like Y, may act as service account Z.”
↩︎ Replacing static keys with federated identity“At least one of subject_prefix, claims, or condition must be set, and all configured matchers must pass for the JWT to be accepted.”
↩︎ Replacing static keys with federated identity“The default is workspace:developer, which grants the same access as a workspace API key.”
↩︎ Replacing static keys with federated identity“You need the admin, owner, or primary owner role in your Anthropic organization”
↩︎ Replacing static keys with federated identity“a workspace API key is a credential, while a service account has credentials.”
↩︎ Replacing static keys with federated identity“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”
↩︎ How a workload exchanges its JWT for a Claude token“The zero-argument form is the recommended pattern for production workloads”
↩︎ How a workload exchanges its JWT for a Claude token“A federation rule (fdrl_...) is the bridge between an issuer and a service account”
↩︎ Checkpoint - 2.
“a long-lived secret one hop upstream (for example, a static cloud credential that can mint IdP tokens) can still undermine it”
↩︎ Replacing static keys with federated identity - 3.
“The minted token is scoped to this workspace at exchange time, so switching workspaces requires a new exchange.”
↩︎ How a workload exchanges its JWT for a Claude token“ANTHROPIC_WORKSPACE_ID is read alongside but does not gate activation.”
↩︎ Which credential the SDK actually uses“environment variables fill any fields the profile omits but never override fields the profile sets explicitly”
↩︎ Which credential the SDK actually uses“The SDK resolves credentials in this order. The first source that yields a credential wins.”
↩︎ Exam trap 1“When omitted, the server selects the rule's sole enabled workspace.”
↩︎ Checkpoint“Shadows federation entirely. Unset these when migrating from API keys.”
↩︎ Prediction“A missing named profile is an error, not a fall-through.”
↩︎ Checkpoint