Workload Identity Federation
Purpose and Scope
Workload Identity Federation lets a workload authenticate to the Claude API without storing a long-lived static API key. In the administrative model, an external identity provider signs an OpenID Connect identity token, Anthropic validates that token against a configured issuer and rule, and the exchange returns a short-lived Anthropic access token for a service account. This page focuses on how that concept appears in the TypeScript SDK: how callers supply identity tokens, how the SDK performs the token exchange, and which runtime constraints matter when the identity token comes from local infrastructure.
Sources: src/lib/credentials/identity-token.ts, src/lib/credentials/oidc-federation.ts
The SDK code deliberately separates two responsibilities. An identity-token provider produces the upstream JWT assertion, while an access-token provider exchanges that assertion for an Anthropic token. That separation is important because different platforms obtain the upstream token differently: Kubernetes may mount a rotating service-account token file, CI systems may expose a job token, and cloud runtimes may mint OIDC tokens through metadata services. The exchange path does not need to know the source; it only requires a function that returns a JWT string when called.
Sources: src/lib/credentials/identity-token.ts, src/lib/credentials/oidc-federation.ts
Relevant Source Files
src/internal/detect-platform.ts- Detects runtime platform details and builds SDK telemetry properties for JavaScript environments such as Node, Deno, Edge, browser, or unknown runtimes.src/lib/credentials/identity-token.ts- Provides helpers for turning a static JWT value or a file-backed JWT into anIdentityTokenProvider.src/lib/credentials/oidc-federation.ts- Implements the OIDC federation access-token provider, request body construction, beta headers, token endpoint call, validation, and error handling.CLAUDE.md- Records repository engineering rules for runtime-agnostic code and Node-only boundaries, which are especially relevant when a credential helper reads from local files.
Core Concepts
Before SDK code can exchange a token, the organization-side federation resources must already exist. Official Claude documentation describes a federation issuer as the trusted OIDC issuer, a federation rule as the claim-matching policy that binds an issuer to a target service account and workspace, and a service account as the non-human Anthropic identity that receives the resulting permissions. In SDK terms, those configured resource identifiers become inputs to the exchange provider: the rule ID, organization ID, optionally a service account ID, and optionally a workspace ID.
Sources: src/lib/credentials/oidc-federation.ts
Workspace selection is not a cosmetic option. The SDK configuration comment states that workspaceId can be a tagged workspace ID or the literal default, and that the minted token is workspace-scoped. It also states that per-request workspace selection through the anthropic-workspace-id header is not supported for federation tokens. If an application needs to act in another workspace, it should perform a new token exchange with a different workspace value rather than trying to reuse one access token across workspace boundaries.
Sources: src/lib/credentials/oidc-federation.ts
Identity Token Providers
The simplest identity-token helper wraps a JWT string with identityTokenFromValue. It validates that the input is not empty and then returns a provider function that yields the same token on each call. This is useful for tests, controlled process injection, or integration layers that already acquired a fresh OIDC assertion elsewhere. It is less appropriate for systems where the identity token rotates automatically unless the caller recreates the provider or supplies a provider function that reads the latest value each time.
Sources: src/lib/credentials/identity-token.ts
For rotating local credentials, identityTokenFromFile reads a file on every call. The source comment explicitly calls out Kubernetes projected service-account tokens as a motivating example, because those files can be updated by the platform while the process remains alive. The helper trims file content, rejects an empty path, wraps file-read failures in AnthropicError, and rejects files whose trimmed content is empty. Because it imports node:fs inside the provider function, use this helper in Node-compatible contexts where local file access is expected.
Sources: src/lib/credentials/identity-token.ts, CLAUDE.md
Federation Exchange Flow
oidcFederationProvider returns an async access-token provider. Each invocation first requires a secure token endpoint, asks the configured identity-token provider for a JWT assertion, and performs a client-side length check. The code rejects assertions larger than sixteen kibibytes with WorkloadIdentityError, giving operators an immediate signal that a projected token or upstream identity source is misconfigured. This preflight check avoids an opaque server failure and makes federation setup problems easier to diagnose during deployment.
Sources: src/lib/credentials/oidc-federation.ts
After validation, the provider builds a JSON request body for the RFC 7523 jwt-bearer grant. The body always includes the grant type, assertion, federation rule ID, and organization ID. It conditionally includes a service account ID and workspace ID when supplied. The provider then posts to the configured base URL plus the SDK token endpoint, sends JSON content, includes the OAuth and federation beta header values, and sets a User-Agent that identifies the TypeScript SDK version unless the caller provided an override.
Sources: src/lib/credentials/oidc-federation.ts
Error handling is part of the public behavior developers should plan around. If the fetch call itself fails, the provider throws WorkloadIdentityError with the token endpoint URL and original error. If the endpoint responds with a non-success status, the code reads the response body when possible and redacts sensitive material before surfacing diagnostic details. The source comment notes that authentication failures can be hard to debug from status alone, so the implementation adds guidance around federation rule configuration and workspace selection.
Sources: src/lib/credentials/oidc-federation.ts
Compact API Reference
| Component | Inputs | Behavior |
|---|---|---|
identityTokenFromValue(token) | Non-empty JWT string | Returns an IdentityTokenProvider that resolves to that string. |
identityTokenFromFile(path) | Non-empty file path | Reads and trims the file on every call, enabling rotation-aware JWT loading. |
oidcFederationProvider(config) | identityTokenProvider, federationRuleId, organizationId, baseURL, fetch, optional serviceAccountId, workspaceId, userAgent | Returns an AccessTokenProvider that exchanges the external JWT for an Anthropic access token. |
OIDCFederationConfig.workspaceId | Tagged workspace ID or default | Scopes the minted token to that workspace; changing workspaces requires another exchange. |
The exchange provider is intentionally uncached. Its source comment says every invocation performs a fresh token exchange and recommends wrapping it in a token cache to avoid exchanging on every request. The same comment states that federation grants do not return refresh tokens, so callers should re-exchange their assertion when the Anthropic token expires. In practice, production clients should combine a rotation-aware upstream assertion source with access-token caching, while still allowing the cache to expire early enough to avoid sending stale credentials.
Sources: src/lib/credentials/oidc-federation.ts
Runtime and Implementation Notes
Runtime boundaries matter because federation credentials often come from platform-specific sources. The repository guidance says code that references Node builtins must be isolated from runtime-agnostic SDK internals, and it warns that bundlers follow statically resolvable imports. That guidance is relevant when choosing the file-backed helper: a server process can read a projected token file, but browser and edge deployments usually need a different identity-token provider. Treat the provider abstraction as the portability layer, and keep platform-specific acquisition code at the application boundary.
Sources: CLAUDE.md, src/lib/credentials/identity-token.ts
The SDK also includes platform detection code that classifies Deno, Edge Runtime, Node, browser, or unknown environments and builds X-Stainless-* metadata values with package version, OS, architecture, runtime, and runtime version. This detection is not the federation protocol itself, but it explains how the SDK identifies the environment around outgoing requests. For Workload Identity Federation, the core dependency remains the configured fetch implementation and a valid identity-token provider; platform detection supports observability and compatibility rather than replacing authentication configuration.
Sources: src/internal/detect-platform.ts, src/lib/credentials/oidc-federation.ts
Next Steps
To implement federation, first configure the administrative resources in the Claude Console: issuer, federation rule, service account, workspace membership, and any claim restrictions required by your identity provider. Then choose or write an IdentityTokenProvider that returns the upstream JWT for your workload environment. Finally, create an access-token provider with oidcFederationProvider, pass the configured identifiers, and add caching around the provider if your request volume is more than occasional. Review authentication configuration, Admin API setup, and provider-specific SDK pages when combining federation with cloud runtimes or CI systems.