CCDV-F 7.4 — Identity, secrets and keys

Where a credential should live at each stage

Developer machinelocal env file, never committed
CI pipelineinjected secret, masked in logs
Stagingown key, own workspace, own limits
Productionshort-lived token from your identity provider

The same application, three environments, three separate credentials. Nothing is shared downward, and nothing is committed at any stage.

Where secrets must not be

Start with the negative rules, because they account for most real incidents. A key does not belong in source code, in a committed configuration file, in a container image, in a log line, in an error message shown to a user, or in a prompt. The SDKs read ANTHROPIC_API_KEY from the environment by default precisely so that the key never has to appear in your code at all; in production it comes from a secret manager and is injected at deploy time.

One rule is specific to this API and easy to get wrong: a browser must never hold a Claude API key. The documentation notes that browser requests need a backend proxy — anything shipped to a front end is readable by anyone who opens the developer tools, and a key in a mobile binary is no better. Your server holds the credential, authenticates your own user, and calls the API on their behalf.

The prompt is the other place people forget. A key pasted into a system prompt so a tool can “use it” is now inside the context window, subject to everything in 7.1 about prompt leak. Credentials belong in the code that runs the tool, never in the text the model reads.

Scoping: workspaces, keys and roles

A Claude organisation can be divided into workspaces, and a workspace is the unit of isolation that matters for this objective. Workspaces separate API keys, spend limits, rate limits, members and their roles, and usage tracking, while billing and administration stay central. The documented uses are exactly the ones you want: one workspace per environment, per team or per product, each with its own limits.

That isolation is what turns a credential incident into a contained one. A key scoped to the staging workspace cannot spend the production budget or read production-scale rate limits, and a spend cap on a workspace bounds the damage of a leaked key or a runaway loop. Per-workspace usage also makes the cost attribution in 5.4 possible.

Level	What it grants	Use it for
Organisation `admin`	Manage users and everything below	A small number of named people
Organisation `developer`	Use the playground and manage API keys	Engineers who provision keys
Organisation `user`	Playground access only	Everyone else
Workspace Admin	Full control of that workspace's settings and members	The team that owns the environment
Workspace Developer	Create and manage keys, use the API in that workspace	Day-to-day engineering
Service account	A non-human identity that keys and tokens act as	Applications and pipelines, never a person's key

Use a service account for anything automated. A production service running on a named engineer's personal key is an outage waiting for that engineer to leave, and it destroys accountability: every audit trail points at a person who was asleep at the time. Access approval and level verification, in the objective's words, means someone with the authority to grant it deciding which role an identity gets, and that decision being reviewable later.

Worked example · One key, four environments, and a bad Tuesday

A start-up ships fast. A single API key lives in the team password manager and is used by local development, CI, staging and production. A contractor's laptop is stolen.

The immediate problem. Rotating the key stops the thief and every deployment at the same time, because there is only one key.
What they do first. Revoke and reissue anyway. A brief outage is cheaper than an unknown party with production access, and hesitating over that is how small incidents become large ones.
The structural fix. Four workspaces — development, CI, staging, production — each with its own keys, spend cap and rate limits.
Separate the identities. CI and production move to service accounts; human keys are used only for local development and the playground.
Make the next rotation boring. Keys are read from the secret manager at deploy time, so reissuing one is a configuration change rather than a code change.
Verify it worked. The usage report is grouped by API key, confirming that no traffic from the old key remains anywhere.

Takeaway: The cost of the incident was set months earlier, by the decision to share one credential. Scoping is what makes revocation a routine action instead of a crisis.

Better than a secret: federated identity

The strongest version of secret management is not having a long-lived secret at all. Workload identity federation lets a workload prove who it is with a signed token from your own identity provider — a cloud IAM role, a CI provider, a Kubernetes service account — and exchange it for a short-lived Claude access token bound to a service account. There is no static key to mint, store, rotate or leak.

A federated credential, end to end

Workload

Your IdP

Anthropic

Request identity token

Signed JWT with claims

Exchange at the token endpoint

Verify signature, match rule

Short-lived access token

Call the API; refresh before expiry

The only durable thing here is a configured rule. The credential in flight expires in minutes and the SDK refreshes it before it does.

Three things are configured once: a service account — the non-human identity the token acts as; a federation issuer — your identity provider, registered with its issuer URL and the public keys used to verify its signatures; and a federation rule — the bridge that says which claims from that issuer may assume which service account, with which scope and token lifetime. Anthropic validates the incoming token against the issuer's keys and the rule's conditions before issuing anything.

Static key against federated identity

Long-lived API key

Valid until someone revokes it
Must be stored somewhere, by someone
Rotation is a scheduled chore
Trust rests on where the string is kept

Federated short-lived token

Expires in minutes; the SDK refreshes it
Nothing durable to store
Rotation is the normal operation
Trust rests on your identity provider's controls

Both authenticate. Only one of them makes “a key leaked” a survivable Tuesday by construction rather than by process.

Monitoring authorised access

The last clause of the objective is about knowing who has access and noticing when that changes. The Admin API is the instrument: it manages organisation members and their roles, invites, workspaces and workspace members, and service accounts, and it lists API keys with their status and expiry so you can find the ones nobody is rotating. It deliberately cannot call the Messages API — an admin credential is for administration only, which is itself a least-privilege design worth copying.

Finding keys that need attentionpython

# Admin credentials only — this key cannot call the Messages API.
keys = client.beta.organization.api_keys.list(status="active")

for k in keys:
    stale = k.expires_at is None                  # no expiry set at all
    if stale:
        report(f"{k.name} ({k.id}) has no expiry — schedule rotation")

# Pair it with spend: the usage report groups by api_key_id, so a key
# that appears in the key list but never in usage is a key to revoke.

Two habits do most of the work. Review membership and roles on a schedule, and remove people when they leave — offboarding through the API is the documented approach, and it is the step most often skipped. And watch usage per key: a key with no traffic is a key to revoke, and a key whose traffic suddenly changes shape is worth a question. Anthropic's own recommendations are exactly this — audit roles regularly, monitor key usage and expiry, rotate periodically, clean up unused workspaces and expired invites.

A credential hygiene review

Passes: No credential in source control, images or logsScan history, not just the current tree
Passes: Separate keys per environment, in separate workspacesSpend and rate limits set per workspace
Fails: Applications and pipelines use service accountsA personal key in production breaks the audit trail
Fails: Keys have an expiry, and rotation is a config changeList keys and check expires_at
Passes: No API key reachable from a browser or mobile clientCalls go through your own backend
Check: Membership and roles reviewed; leavers removedAutomate offboarding through the Admin API
Check: Usage monitored per key, with alerts on anomaliesA quiet key and a suddenly busy key both deserve attention

Nothing here is exotic. The two failing rows are what turn an ordinary mistake into an incident.

Worked example · The key in the public repository

A developer pushes a prototype to a public GitHub repository. The key is in a committed .env file. Within an hour, spend on that workspace rises sharply.

Revoke first. The key is disabled in the console before anything else is discussed. Everything after this is clean-up.
Reissue narrowly. The replacement is a workspace-scoped key with a spend limit, not a copy of the old arrangement.
Assess the blast radius. The usage report, grouped by key, shows what was called and when, and that only the prototype workspace was affected — which is the argument for having had workspaces.
Remove the path, not just the file. Deleting the file does not remove it from history; the repository is treated as compromised and the secret considered public forever.
Prevent the repeat. Pre-commit secret scanning, .env in the ignore file from the template onwards, and local development moved onto a personal low-limit key.
Write it down. A short runbook: revoke, reissue, assess, scan, review — so the next person does not have to decide in a hurry.

Takeaway: Speed of revocation, and the spend limit that was already in place, decided the size of this incident. Both were set up long before the mistake happened.

Traps the wrong answers are built from

Tempting but wrong	Do this instead
Committing a key and fixing it by deleting the file	Revoke and reissue first; history and logs keep the old value forever.
One shared key across development, CI, staging and production	A key per environment in its own workspace, with its own spend and rate limits.
Calling the Claude API directly from a browser or mobile app	Keep the credential server-side and proxy the call through your own backend.
Running production on a named engineer's personal key	Use a service account, so access survives the person and the audit trail names the system.
Putting a credential in the system prompt so a tool can use it	Keep secrets in the code that runs the tool; the context window is not a vault.
Leaving `ANTHROPIC_API_KEY` set after migrating to federation	Clear it everywhere — it takes precedence and silently keeps the old key alive.
Provisioning access and never reviewing it	Audit members, roles and key expiry on a schedule, and automate offboarding.

You should now be able to

Keep credentials out of source, images, logs, browsers and prompts, and load them from the environment or a secret manager.
Scope access with workspaces, per-environment keys, spend and rate limits, and appropriate roles.
Choose service accounts for automated workloads and explain why personal keys fail there.
Describe workload identity federation and what it replaces.
Respond to an exposed key in the right order: revoke, reissue, assess, clean up.
Monitor authorised access with the Admin API — roles, key status and expiry — and act on what it shows.

Identity, secrets and keys