What you will be able to do
- Give each workload and end user its own identity, using service accounts, identity-backed keys and per-user vaults
- Replace a static Claude API key with Workload Identity Federation and migrate without downtime
- Keep credentials out of the model's reach by having the platform add them to requests at egress
- Scope tokens, workspaces and tools to least privilege
- Design an audit trail that records who did what without creating a new store of secrets
Key concept
Identity-bound, short-lived credentials — Every workload or agent acts as a named, non-human identity, and the credentials it holds expire in minutes and are never seen by the model. Access then follows the identity's scope and lifetime. Nobody has to track down every copy of a long-lived secret.
1.Give every workload and user its own identity
Agent security starts with being able to say who acted. A production Claude deployment usually acts for two kinds of principal: the workload itself (a CI job, a support service, a Kubernetes deployment) and the end user that workload serves. When either one shares a credential with others, you cannot revoke access precisely, and the logs cannot tell you who did what.
For workloads, the identity is a service account (svac_...). A service account is a named, non-human principal that lives at the organization level and becomes active in a workspace when you add it as a member. It has no email, no password and no Console login. The distinction that matters is that a workspace API key *is* a credential, whereas a service account *has* credentials. Those credentials can be replaced, and the identity stays the same.
| Key type | Acts as | Stops working when |
|---|---|---|
| Personal key | You, with your roles and permissions | You lose access to the organization |
| Service account key | A service account | The service account is archived |
| Workspace key (legacy) | No one: it belongs to the workspace | It expires, is disabled or deleted, or its workspace is archived, even if its creator leaves |
Personal keys and service account keys are identity-backed: when the owning identity is removed from the organization, its keys stop working. That matters when someone leaves. A shared personal key acts as one person and breaks when they leave, and a legacy workspace key keeps working after its creator is gone. For CI and production services, an admin should create a service account so the workload has its own identity.
End users need identities too. In Claude Managed Agents, a vault holds the credentials of one end user. You can tag it with metadata such as external_user_id to map it back to your own user records. You pass the vault through vault_ids when you create a session, so the agent definition describes the product and the session carries the user. Without this, you can lose track of which end user an agent acted for. A shared static bearer token on a team MCP server has the opposite problem: anyone who ever held a copy, including a departed engineer, can still act. A credential per user, held in a vault and revocable on its own, removes that exposure.
Checkpoint 1 of 9· Check yourself
A production support service calls the Claude API. You want its actions to show up in logs under a name you can attribute, and you want to be able to rotate its credentials without changing who it acts as. What should the service authenticate as?
A service account is a named, non-human identity that holds credentials, so you can rotate those credentials and it stays the same identity. A personal key acts as one person and breaks when they leave. A legacy workspace key acts as no one. A vault holds an end user's credentials and does not give the workload its own identity.
“A workspace API key is a credential, whereas a service account has credentials.”Source: platform.claude.com
2.Workload Identity Federation replaces static API keys
A long-lived sk-ant-... key is a secret that has to be stored somewhere. Wherever it is stored, it can leak. Encrypting it in a CI variable, masking it in logs, limiting it to an IP range or decrypting it with KMS just before use all reduce the exposure, but each one leaves a stored Claude credential behind. Workload Identity Federation (WIF) removes the stored credential. The workload presents a short-lived OIDC token issued by an identity provider it already has: GitHub Actions, AWS IAM, Google Cloud, Kubernetes, Microsoft Entra ID, Okta or SPIFFE.
You set up three resources in the Claude Console:
- a federation issuer (
fdis_...), which registers the identity provider by its exactissURL and a JWKS source for verifying signatures - a service account (
svac_...), the identity the token acts as - a federation rule (
fdrl_...), which says that a JWT from issuer X whose claims look like Y may act as service account Z with scope S
At runtime the SDK posts the JWT to POST /v1/oauth/token using the RFC 7523 jwt-bearer grant. Anthropic checks it against the issuer's keys and the rule's match conditions, then returns an sk-ant-oat01-... token. The client names the rule to use, and there is no implicit search across rules. A rule can match on a subject_prefix, an exact audience, exact claim values, or a CEL condition, and all configured matchers must pass.
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_...",
),
)Several limits keep the minted token short-lived:
token_lifetime_secondsranges from 60 to 86,400. The API default is 3,600, and the Console wizard prefills 600.- The token never lives longer than twice the remaining lifetime of the IdP JWT it came from, so it cannot outlive the upstream identity by more than a small margin.
- A JWT that carries a
jticlaim is single-use by default. A retry loop that resends a cached JWT fails withjti_reused.
The SDK refreshes the token before it expires and rereads ANTHROPIC_IDENTITY_TOKEN_FILE on every exchange, so projected tokens that rotate on disk keep working.
Federation is only as strong as 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. Tight match conditions matter for the same reason. For SPIFFE, the guidance is to pin subject_prefix to a full workload ID and always require an audience.
| Order | Source |
|---|---|
| 1 | Constructor argument (API key, auth token, or credentials) |
| 2 | ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN |
| 3 | ANTHROPIC_PROFILE |
| 4 | Federation environment variables |
| 5 | Active profile |
The migration order follows from that table:
- Configure federation alongside the existing key, and confirm the rule matches the workload's token.
- Run
ant auth statusand confirm the API key still wins at this stage. - Unset
ANTHROPIC_API_KEYfrom CI secrets, the container environment and shell profiles, then checkant auth statusagain. - Once the workload is running on the federated token, delete the key.
Claude Code and the Agent SDK follow the same resolution order, so a federation profile authenticates them too.
Checkpoint 2 of 9· Fill the gap
This client swaps an OIDC token from its identity provider for a short-lived Anthropic token. Anthropic does not search across rules for a match. Which parameter tells the exchange which trust rule to check the JWT against?
from anthropic import Anthropic, WorkloadIdentityCredentials, IdentityTokenFile
client = Anthropic(
credentials=WorkloadIdentityCredentials(
identity_token_provider=IdentityTokenFile(
"/var/run/secrets/anthropic.com/token"
),
? ="fdrl_...",
organization_id="00000000-0000-0000-0000-000000000000",
service_account_id="svac_...",
workspace_id="wrkspc_...",
),
)The client names the federation rule (fdrl_...) in the exchange request. Anthropic checks the JWT only against that rule's match conditions and does not search other rules. The issuer (fdis_...) only registers the identity provider, and the scope is set on the rule, not by the client.
Source: platform.claude.comCheckpoint 3 of 9· Exam question
Hollow Insurance runs a nightly CI pipeline that calls Claude to summarize claims batches for its production reporting system. The pipeline authenticates with an API key stored as a long-lived CI secret. Twice this year that key appeared in build logs, even though log masking was already enabled and the key was rotated each time afterward. Each stage's runner can read the secret store, and the CI platform issues every job a signed identity token naming the repository and branch. The security team's audit finding is that no Claude credential should remain stored in the pipeline's secret store or on its runners, whether encrypted or plaintext, regardless of how often it is rotated. Which change best meets this requirement?
Correct answer: C — Have the job send its platform OIDC identity token to a federation endpoint, and use the temporary credential it returns for that run.
- A. Masking only hides the value in log output. The pipeline still holds a static key in the CI store, and a manual ninety-day rotation leaves a leaked key usable for weeks, so the stored-credential requirement is not met.
- B. Separate keys limit how much one leak exposes, but each is still a static secret kept in the CI store. An IP restriction does not help when the key is read from inside the runner, so the pipeline still holds stored credentials.
- C. Workload identity federation lets the job prove who it is with a signed OIDC token issued by the CI platform and trade it for a temporary credential. The pipeline then has no stored Claude secret to leak, store or rotate.
- D. KMS encryption protects the key at rest, but the job must still decrypt the same static key and hold the plaintext in memory or the environment during the call. A long-lived Claude key therefore remains part of the pipeline.
Sources1
3.Keep credentials out of the model's reach
Anything in Claude's context can come back out. A token placed in the system prompt so Claude can write an Authorization header can be pulled out by a poisoned document. Telling Claude not to reveal it, scanning its output for token-shaped strings, or shortening the token's life all leave the secret in the context window. The direct fix is structural. Claude asks for the action, and the tool code or an egress proxy attaches the credential when the request leaves. The model never holds the secret. Keep keys out of system prompts, agent definitions and messages. Injection paths themselves are covered in prompt injection and threat defense.
Managed Agents builds this pattern into vaults. An environment_variable credential sits in the sandbox as an opaque placeholder. The real value is substituted only in outgoing HTTPS requests to the hosts the credential allows, and the agent never sees it. Secret values are write-only and are never returned in API responses. With a self-hosted sandbox, you get the same behaviour by running your own proxy that replaces placeholders with real secrets at egress.
env_credential = client.beta.vaults.credentials.create(
vault_id=vault.id,
display_name="Notion API key for sandbox",
auth={
"type": "environment_variable",
"secret_name": "NOTION_API_KEY",
"secret_value": "ntn_your-secret-here",
"networking": {
"type": "limited",
"allowed_hosts": ["api.notion.com"],
},
"injection_location": {"header": True},
},
)Two settings narrow where the secret goes. networking limits which hosts receive it, and injection_location limits which part of the request carries it. Header-only is the narrower choice, because request bodies are often built from content the agent has read. Leaving injection_location out on create enables both locations, so name both fields. Avoid allowed hosts that echo request headers back, because responses reach the sandbox unredacted.
Substitution only works on outbound requests. If code in the sandbox uses a stored secret to fetch a session token, such as an OAuth client-credentials grant, that token comes back unredacted. Do the exchange yourself and store the resulting token in the vault. For the same reason, never give the agent a Claude API key or access token, even in a vault. Code in the sandbox could call the Claude API directly, and the agent's tool settings, approvals and budget do not apply to those calls.
Checkpoint 4 of 9· Check yourself
An agent on Managed Agents must call a third-party API that issues short-lived session tokens through an OAuth client-credentials grant. You plan to store the client secret as an environment_variable vault credential and let code in the sandbox run the grant. What is wrong with this plan, and what should you do?
Vault substitution happens only on outbound requests. A token that the sandbox gets back by using the stored secret arrives unredacted, so the agent could see it. Do the exchange outside the sandbox and store the resulting token in the vault. Leaving injection_location out on create turns on both locations, not header only. Limited networking controls which hosts get the secret, and it does not redact responses.
“Fetch third-party tokens yourself and store them in the vault. A token that code in the sandbox fetches with a stored secret comes back unredacted.”Source: platform.claude.com
Checkpoint 5 of 9· Exam question
Cobalt Retail runs a production billing agent that calls an internal invoicing API. Developers placed the bearer token in the system prompt so Claude can write the Authorization header for each request. During a red-team exercise, a poisoned support document in the retrieval index told the agent to repeat its configuration, and the token was extracted. The prompt already instructed Claude never to reveal the token, but the injected text overrode that instruction. A follow-up test leaked the token again when the agent was asked to return it base64-encoded in pieces across several replies. Security notes that the token is already rotated daily, yet the stolen copy worked immediately. Compliance requires that a successful injection must not be able to reveal any credential at all. What is the most direct fix?
Correct answer: A — Have the tool code or an egress proxy attach the credential when the API call is sent, with Claude only requesting the action to perform.
- A. Injecting the credential in tool code or at an egress proxy keeps the secret out of the context window. A poisoned document then has nothing to extract, because Claude only names the action and never sees the value.
- B. A prompt instruction is exactly what text in an injected support document can override or talk around. The credential also stays in context, so a successful injection can still read it out and the rule enforces nothing.
- C. A filter only inspects output after the secret is already in context. Encoded, split or paraphrased variants can pass a pattern match, so it treats the symptom while the model still holds the credential.
- D. Short lifetimes and rotation shrink how long a stolen credential works, but it is still in the prompt. The same injection can extract it again, and the copy works until it expires.
4.Least privilege for tokens, workspaces and tools
A federation rule's oauth_scope sets a ceiling on what the minted token can do. Effective permissions are the intersection of the rule's scope and the target service account's organization_role. An admin service account behind a workspace:developer rule gets Claude API access in one workspace and nothing more. A rule that grants org:admin must target an admin service account. A call outside the token's scope returns HTTP 403.
| oauth_scope | Grants |
|---|---|
| workspace:inference | Messages, Models and the OpenAI-compatible chat endpoint in the rule's workspace |
| workspace:manage_tunnels | The MCP tunnels API only |
| workspace:developer | All non-administrative Claude API endpoints in the workspace, the same as a workspace API key |
| org:admin | Full Admin API access |
Scopes go no finer than this. You cannot scope by resource, or by read versus write. A workload that only calls Claude should get workspace:inference, and finer isolation comes from workspaces. Keep vaults for workloads with different trust levels in separate workspaces, because anyone who can start sessions in a workspace can reference its vaults. Limit each workload to one workspace: preferably a WIF rule enabled only there, otherwise an API key scoped to it.
Tools follow the same rule. In Managed Agents:
- Set the toolset's
default_config.enabledtofalse, then enable only the tools the agent needs. - Never give an agent that reads untrusted input an
always_allowtool that writes files, runs commands or changes records. - Use
always_askwherever a person must review a call.autois a server-side check, not a human checkpoint.
Keys held in a vault need the same treatment at the service that issued them. The agent can do anything the key allows. Run-time enforcement through permission modes, hooks and canUseTool belongs to runtime guardrail systems.
Checkpoint 6 of 9· Match them up
Each federation rule below sets the scope of the token it mints. Match each oauth_scope to what that token can call.
Tap a term, then the definition that fits it.
The four scopes run from narrowest to broadest. No scope is finer than these, so you cannot limit a token by resource or by read versus write. A workload that only calls Claude should get workspace:inference rather than the default, workspace:developer.
“Use this for workloads that only need to call Claude and never need to manage Files, Skills, or other resources.”Source: platform.claude.com
Checkpoint 7 of 9· Check yourself
Your Managed Agents triage agent reads inbound customer emails and holds a tool that issues refunds in your billing system. Compliance requires a person to approve every refund before it is issued. Which permission_policy should the refund tool have?
Only always_ask holds each call for a person to review. auto lets the server run, deny or pause a call based on its own check, so it is not a human checkpoint. always_allow is also ruled out, because this agent reads untrusted input and the tool changes records.
“auto is not a human checkpoint, so if a person must review a tool’s calls before they run, configure always_ask on that tool.”Source: platform.claude.com
5.Audit logging of security-relevant agent actions
An audit trail has to answer who acted, with which tool, on what, and what decision was made, without becoming a second store of the secrets and personal data it describes. Identity comes first. Because each workload authenticates as its own service account, the logs can attribute actions to it. When a federated exchange fails, the authentication history page in the Claude Console shows the deny reason.
Claude Code's OpenTelemetry events show the split between metadata and content. A tool_decision event records whether a tool call was allowed or denied, where the decision came from (configuration, a hook or the user), tool_name, permission_mode and tool_use_id. A permission_mode_changed event records escalations with from_mode, to_mode and trigger. Tool arguments are not logged by default and appear only when you set OTEL_LOG_TOOL_DETAILS=1. Raw tool output appears in spans only with OTEL_LOG_TOOL_CONTENT=1. This data goes only to the OTEL endpoint you configure, never to Anthropic.
| Data | Example | Retention approach |
|---|---|---|
| Decision metadata | tool_decision with decision, source, tool_name, tool_use_id | Keep long term as the core audit trail |
| Tool arguments | tool_parameters, only with OTEL_LOG_TOOL_DETAILS=1 | Filter or redact in the telemetry backend before storage |
| Raw content | tool.output, only with OTEL_LOG_TOOL_CONTENT=1 | Restricted store, shorter retention |
When you do capture arguments and results, assume they hold sensitive values, because pasted credentials and personal data show up in them. Redaction belongs in a deterministic filter in the telemetry pipeline that runs before the record is written. Asking Claude to summarize or drop sensitive values does not work: the model has already seen the value, and its output can be steered by the same content it is reading. Turning off logging for sensitive tools is also wrong, because it deletes the trail for exactly the actions compliance cares about. Copying full payloads into a shared debug store widens access to the data you were trying to protect.
Managed Agents gives you the retention controls. Webhooks alert when a session goes idle, reaches its budget or terminates. Store the events you want to keep in your own logs, and delete sessions you no longer need. Correlate the long-term metadata with any short-retention content through shared identifiers such as tool_use_id and session.id, rather than by keeping the content itself.
Checkpoint 8 of 9· Check yourself
Compliance wants a lasting record of what your Managed Agents sessions did, plus a prompt alert when a run stalls or runs out of budget. They also want as little sensitive content kept as possible. Which approach fits the lesson's guidance?
Managed Agents gives you the retention controls: webhooks alert when a session goes idle, reaches its budget or terminates, and you keep the events you need in your own logs and delete sessions you no longer need. Relying on session history alone holds more content than you need and gives no prompt alert. A shared debug store gives more people access to the data you are trying to protect. Turning off capture for sensitive tools removes the record of exactly the actions compliance cares about.
“Store the events you want to keep in your own logs, and delete sessions you no longer need”Source: platform.claude.com
Checkpoint 9 of 9· Exam question
Alder Bank runs a production agent that handles customer support tickets. Every agent turn is written to an audit log, and the entries capture full prompts and complete tool results. A sample review found that these entries contain customers' account details and addresses, and that agents sometimes paste API keys or passwords into ticket text, which then appear verbatim in the log. The log store is readable by the whole platform team. The compliance office requires an investigable trail showing who acted, which tool ran, on which resource, and what was decided, for several years. It also requires that the trail not create new exposure of personal data or credentials. An earlier proposal to simply keep everything as is was rejected. Which TWO actions best meet these requirements? Select two.(Select 2)
Correct answers: A, B — Keep structured metadata such as identity, tool, resource and decision long term; hold raw content in a restricted store with shorter retention.; Pass tool arguments and results through a deterministic scrubber that removes secrets before the write, keeping a digest for correlation.
- A. Separating long-lived metadata from short-lived, access-controlled content preserves accountability while limiting how long and how widely sensitive text is held.
- B. A deterministic scrubber removes credentials regardless of model behaviour, and a digest still lets investigators match entries without storing the secret.
- C. Disabling logging for the most sensitive tools removes the audit trail exactly where it matters most and fails the compliance requirement.
- D. Putting raw content into a broadly readable debug store widens access to personal data and credentials, which is the exposure the team wants to avoid.
- E. Asking the model to omit values is a prompt-level control that can fail silently, and the unredacted result may already have been logged by then.
Practise it for real
Move one workload from a static ANTHROPIC_API_KEY to Workload Identity Federation without downtime.
1.In the Claude Console, open Workload identity, select Connect workload, choose your provider and finish the wizard. Leave ANTHROPIC_API_KEY in place.
Why: This creates the issuer, service account and rule while the existing key keeps the workload running.
You should see: An fdrl_... rule ID and an svac_... service account ID, plus a successful test exchange within the 15-minute window.
2.Inject ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID and ANTHROPIC_IDENTITY_TOKEN_FILE into the workload, then run ant auth status inside it.
Why: This confirms which credential source wins.
You should see: The API key still wins, because it ranks above the federation variables.
3.Unset ANTHROPIC_API_KEY in CI secrets, the container environment and shell profiles, then rerun ant auth status.
Why: A leftover key anywhere in the environment overrides federation.
You should see: The federation source is now reported as the winner, and API calls still succeed.
4.Delete the old key on the API keys page.
Why: Disabling a key is reversible, so deleting it is what removes the stored secret for good.
You should see: The key is listed with status archived, and the workload keeps running on short-lived sk-ant-oat01- tokens.
Stuck? Get a nudge
If the exchange returns 401, check the authentication history page in the Console for the deny reason. An issuer URL mismatch or a reused jti are common causes.
Sources
(6)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Unlike a human user, a service account has no email, no password, and no Console login.”
↩︎ Give every workload and user its own identity“A workspace API key is a credential, whereas a service account has credentials.”
↩︎ Give every workload and user its own identity“There are no static secrets to mint, store in CI, rotate, or leak.”
↩︎ Workload Identity Federation replaces static API keys“The second bound prevents an Anthropic token from outliving the upstream identity it was derived from by more than a small margin.”
↩︎ Workload Identity Federation replaces static API keys“By default, identity tokens that carry a jti claim are single-use.”
↩︎ Workload Identity Federation replaces static API keys“Federated authentication is only as strong as the upstream identity provider that signs the JWT.”
↩︎ Workload Identity Federation replaces static API keys“Because each workload authenticates as a named service account, you can more easily audit which workloads acted as which service account.”
↩︎ Audit logging of security-relevant agent actions“There are no static secrets to mint, store in CI, rotate, or leak.”
↩︎ Key concept“Because ANTHROPIC_API_KEY sits above the federation tiers in the precedence chain, the API key still wins at this stage.”
↩︎ Exam trap 1 - 2.
“When that identity is removed from the organization, the key stops working.”
↩︎ Give every workload and user its own identity“To limit where a leaked key works, turn on IP allowlisting.”
↩︎ Keep credentials out of the model's reach - 3.
“lose track of which end user an agent acted on behalf of”
↩︎ Give every workload and user its own identity“you can run your own proxy that replaces placeholder values with the real secrets at egress.”
↩︎ Keep credentials out of the model's reach“Substitution is outbound only.”
↩︎ Exam trap 2 - 4.
“Keep keys out of system prompts, agent definitions, and messages.”
↩︎ Keep credentials out of the model's reach“The agent’s tool settings, approvals, and budget do not apply to those calls.”
↩︎ Keep credentials out of the model's reach“whoever can start sessions in a workspace can reference its vaults”
↩︎ Least privilege for tokens, workspaces and tools“No agent that reads untrusted input has a tool on always_allow that writes files, runs commands, or changes records”
↩︎ Least privilege for tokens, workspaces and tools“Store the events you want to keep in your own logs, and delete sessions you no longer need”
↩︎ Audit logging of security-relevant agent actions“Fetch third-party tokens yourself and store them in the vault. A token that code in the sandbox fetches with a stored secret comes back unredacted.”
↩︎ Checkpoint“auto is not a human checkpoint, so if a person must review a tool’s calls before they run, configure always_ask on that tool.”
↩︎ Checkpoint - 5.
“A federation rule’s oauth_scope is a ceiling: the minted token can never exceed it.”
↩︎ Least privilege for tokens, workspaces and tools“Finer-grained scopes (by resource, or read versus write) are not available.”
↩︎ Least privilege for tokens, workspaces and tools“Effective permissions are the intersection of the rule’s scope and the service account’s role.”
↩︎ Exam trap 3“Overrides federation entirely. Unset these when migrating from API keys.”
↩︎ Prediction“Use this for workloads that only need to call Claude and never need to manage Files, Skills, or other resources.”
↩︎ Checkpoint - 6.https://code.claude.com/docs/en/monitoring-usageOfficial docs
“Tool input arguments and parameters are not logged by default.”
↩︎ Audit logging of security-relevant agent actions“Arguments may still contain sensitive values, so configure your telemetry backend to filter or redact these attributes as needed.”
↩︎ Audit logging of security-relevant agent actions“Arguments may still contain sensitive values, so configure your telemetry backend to filter or redact these attributes as needed.”
↩︎ Exam trap 4