Claude API Identity: Service Accounts, Workload Identity Federation, and Vaults

1.Three ways to authenticate to the Claude API

Every Claude API request has to prove who is calling. The API accepts three kinds of credential. They differ in how long the credential lives and in where the proof of identity comes from, not in what the caller can reach.

The guidance is to start with API keys: a personal key for your own development, a service account key for anything shared. Move to Workload Identity Federation once your workload already has a platform-issued identity to federate.

Sources1

2.Whose identity an API key acts as

When you create a key, you choose its type. The type decides which identity the key acts as and what ends its life. Personal keys and service account keys are identity-backed: every request acts as a user or service account that your organization manages. Remove that identity and the key stops working, so a key cannot outlive the person or workload it belongs to.

A shared personal key acts as one person and breaks the day they leave. CI and production services should therefore get a service account created by an organization admin. Scope matters as well. A key created for one workspace works only there. A key without a workspace scope must send anthropic-workspace-id on every request. If the header is missing, the API returns a 400 invalid_request_error. If the key's identity cannot access the named workspace, the API returns a 404, exactly as it would for a workspace that does not exist. The Admin API accepts personal or service account keys only when they are not scoped to a workspace.

client = Anthropic()  # reads ANTHROPIC_API_KEY

# Required on every request for a multi-workspace key.
# Omit extra_headers for a single-workspace key.
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    extra_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)

Sources1

3.Workload Identity Federation: validating a workload's identity

Workload Identity Federation (WIF) replaces the stored static secret with a proof of identity the workload already holds: a signed JWT from your own identity provider. On most platforms that JWT is ambient, for example a Kubernetes projected service-account token or the GitHub Actions OIDC endpoint. Before any workload can federate, an admin, owner or primary owner configures three resources in the Claude Console.

At runtime, the SDK posts the JWT to POST /v1/oauth/token using the RFC 7523 jwt-bearer grant. Anthropic checks the signature against the issuer's JWKS, then checks the claims against the rule's matchers: subject_prefix, an exact audience, exact claim values, or a CEL condition. Every matcher you configure has to pass. If they all do, Anthropic returns a short-lived sk-ant-oat01-... token that acts as the rule's service account, and the SDK re-runs the exchange before that token expires. The client names the rule to use by ID, and Anthropic never searches for another rule that might match.

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_...",
    ),
)

For production, Anthropic recommends the zero-argument Anthropic() form instead. Ship one container image everywhere and inject ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID and ANTHROPIC_IDENTITY_TOKEN_FILE separately for each environment.

Sources2

4.Approving access and verifying its level

A matched JWT is only the first check. Two more limit what the minted token can do. The first is workspace. At exchange time, the rule's workspace must be one the service account is a member of, and the token then follows that workspace's rate limits and usage attribution. Every service account belongs implicitly to the default workspace. Any other workspace needs an explicit membership. The second is the rule's authorization. Because one issuer can carry many rules, you can have a separate rule per team, namespace or permission level, each with its own scope and lifetime.

Claude Code self-hosted environments have a similar verification step. Each session gets an sk-ant-cc- token that your own services can verify. Check the signature against Anthropic's JWKS, the issuer, the aud claim against your ccpool_... environment ID, the session_worker role and the expiry. The token proves which session and environment Anthropic issued it for. It does not prove which process presents it, because any tool or MCP server in the session can read it. So scope any credentials you derive from it to a single session, not to everything the session's creator is allowed to do.

Sources23

5.Vaults: end-user credentials for managed agents

Agents often act for your end users against third-party services. Vaults let you register those credentials once, one vault per end user, and reference them by ID when you create a session. MCP credentials (mcp_oauth, static_bearer) are keyed by mcp_server_url and injected when the agent connects to that server. environment_variable credentials are keyed by secret_name and sit in the sandbox as an opaque placeholder, which is replaced with the real value at egress. All secret fields are write-only and never returned by the API.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
    title="Alice's Slack digest",
)

Credentials are not validated when you store them. A bad one shows up only during a session, as an authentication or downstream error. Rotation is simple: update the secret value, and because credentials are re-resolved periodically, running sessions pick up the change without a restart. To monitor credential health, subscribe to webhooks such as vault_credential.refresh_failed, then call mcp_oauth_validate to decide what to do next.

Sources4

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Removing a departing engineer from the organization shuts off every API key they created.Why is that wrong?

   That holds for identity-backed personal keys. A legacy workspace key belongs to its workspace, though, and keeps working after its creator leaves. That is why identity-backed keys or WIF are preferred.

   Covered in Whose identity an API key acts as

2. 2.Once static keys are replaced with Workload Identity Federation, credential security is fully handled.Why is that wrong?

   WIF removes static secrets, but it relies on the identity provider that signs the JWT. Pair it with the IdP's own controls, such as workload identity binding, conditional access and audit logging.

   Covered in Workload Identity Federation: validating a workload's identity

3. 3.Deleting a vault or credential is the correct way to offboard a user when you need to keep an audit record.Why is that wrong?

   Delete is a hard delete that keeps no record. Archive purges the secret payload but keeps the record for auditing.

   Covered in Vaults: end-user credentials for managed agents