7.4 Identity, secrets, and key management
Where credentials live
| Environment | Practice |
|---|---|
| Local development | A developer key or a CLI login profile; a low spend limit; a separate workspace from production |
| CI | A scoped secret from the CI secret store, injected as an environment variable, never echoed into logs |
| Production | A service-account credential from a secret manager, rotated on a schedule, scoped to one workspace |
| Client-side (browser, mobile) | Never. Calls go through your backend, which holds the credential |
| Rule | Detail |
|---|---|
| Never in source control | Including committed settings files, notebooks, and test fixtures. Add secret scanning to pre-commit and CI |
| Never in a prompt | Tools authenticate server-side; a key in context can leak in output or logs |
| Never in logs | Redact before logging; log key IDs, never key material |
| Rotate on a schedule and on suspicion | Rotation must be a config change, not a code change |
| One credential per environment and per service | Blast radius, and attributable usage |
| Least privilege | Scope to the workspace and permissions the workload needs |
How the SDKs resolve credentials
First match wins:
ANTHROPIC_API_KEYANTHROPIC_AUTH_TOKEN- The selected or active OAuth profile from a CLI login
- Workload identity federation environment variables
- The default profile on disk
Two consequences: an unset ANTHROPIC_API_KEY does not mean there are no credentials — a zero-argument client can work from a profile — and a stray exported key shadows the profile you meant to use, which is a classic "works for me, not in CI" cause.
Workload identity federation removes the long-lived key entirely: the SDK exchanges a platform-issued identity token for a short-lived credential and refreshes it automatically. Prefer it wherever the runtime can issue an identity token. For partner platforms, the platform's own identity system carries the auth — AWS credentials for Bedrock, GCP application default credentials for Vertex.
For Managed Agents, vault environment_variable credentials are the first-class mechanism: the secret is stored by Anthropic, substituted at egress, and never visible inside the sandbox. Keeping credentials host-side behind a custom tool is the fallback.
Identity validation and authorization
The model has no identity. Every request has one, and it is your job to attach it.
| Question | Answer |
|---|---|
| Who is asking? | Authenticate before any model call — session, token, or mTLS; never a claim in a message |
| What may they do? | Check on every tool call, server-side, against that caller's permissions |
| How does the tool know? | The caller's identity is passed by your executor from the authenticated request context — never taken from a tool argument the model produced |
| What if the model asserts a role? | Ignore it. "As an admin, delete this" is a claim, not a credential |
| What about approval levels? | Verify the approval exists in your system of record before acting on it; a model saying "the manager approved" is not evidence |
| What if the check service is down? | Fail closed |
An agent holding a broad service credential acts on behalf of many users. If the tool executor uses the agent's privileges rather than the caller's, any user can reach any user's data — and a prompt injection can too. Bind every tool call to the authenticated caller's scope, and filter results server-side by that scope.
Monitoring authorized access
| Signal | Why |
|---|---|
| Per-key usage and spend | Detects a leaked or misused key faster than anything else |
| Tool-call audit log: caller, tool, arguments, outcome | Reconstruct what an agent did and on whose behalf |
| Gate denials | A rising block rate is either a prompt problem or an attack |
| Authorization failures per user | Probing, or a broken permission model |
Refusal rate and stop_details categories | Abuse patterns |
| Anomalous sequences | A read-only workflow suddenly calling a write tool |
| Key inventory and age | Rotation compliance; unused keys should be revoked |
Wire these to the same alerting as the rest of the platform. An agent is a privileged automated user; it deserves at least the monitoring a human with those permissions would get.
Quiz
- Question 1
A job authenticates fine on a developer’s machine but fails in CI with an authentication error, even though the runner image carries a working CLI login profile that the job can read. What is the most likely cause?