Skip to main content

7.4 Identity, secrets, and key management

Where credentials live​

EnvironmentPractice
Local developmentA developer key or a CLI login profile; a low spend limit; a separate workspace from production
CIA scoped secret from the CI secret store, injected as an environment variable, never echoed into logs
ProductionA 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
RuleDetail
Never in source controlIncluding committed settings files, notebooks, and test fixtures. Add secret scanning to pre-commit and CI
Never in a promptTools authenticate server-side; a key in context can leak in output or logs
Never in logsRedact before logging; log key IDs, never key material
Rotate on a schedule and on suspicionRotation must be a config change, not a code change
One credential per environment and per serviceBlast radius, and attributable usage
Least privilegeScope to the workspace and permissions the workload needs

How the SDKs resolve credentials​

First match wins:

  1. ANTHROPIC_API_KEY
  2. ANTHROPIC_AUTH_TOKEN
  3. The selected or active OAuth profile from a CLI login
  4. Workload identity federation environment variables
  5. 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.

QuestionAnswer
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
The confused-deputy shape

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​

SignalWhy
Per-key usage and spendDetects a leaked or misused key faster than anything else
Tool-call audit log: caller, tool, arguments, outcomeReconstruct what an agent did and on whose behalf
Gate denialsA rising block rate is either a prompt problem or an attack
Authorization failures per userProbing, or a broken permission model
Refusal rate and stop_details categoriesAbuse patterns
Anomalous sequencesA read-only workflow suddenly calling a write tool
Key inventory and ageRotation 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​

  1. 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?