The classic twelve-factor rule — store config in the environment, keep processes identical across environments — maps cleanly onto the Claude SDKs. Because every official SDK reads its credentials and settings from environment variables when you construct a client with no arguments, the same binary or container image can serve dev, staging, and production with nothing changed but the environment it launches into.
Start with the boundary: one workspace per environment
Before touching client code, draw the boundary server-side. The Claude Console lets workspaces scope API keys by project or environment, so the clean pattern is a workspace each for dev, staging, and production. Each environment then holds only its own key; rotating or revoking the staging key cannot disturb production, and usage rolls up separately per workspace. On Claude Platform on AWS the same idea applies with sharper edges: workspaces are the primary IAM resource and are bound to a single AWS region, and usage, quotas, cost, files, and batches all roll up per workspace — so per-environment workspaces double as per-environment access-control and cost boundaries.
Environment-agnostic code
The application should construct its client with no environment-specific literals at all:
from anthropic import Anthropic
# Identical in every environment.
# Dev shell, staging container, and prod pod each
# supply their own ANTHROPIC_API_KEY (or WIF vars).
client = Anthropic()
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": "ping"}],
)What differs per environment is only what the environment injects: a workspace-scoped ANTHROPIC_API_KEY in dev, and ideally Workload Identity Federation variables in staging and production, so those environments hold no static secret at all. If different environments need different API hosts (say, staging routes through a gateway), ANTHROPIC_BASE_URL carries that too — see the base URL article.
Dotenv in development — with discipline
Locally, developers commonly keep a .env file that their tooling loads into the process environment. That's fine as convenience, with two rules. First, the .env file never enters version control — commit an .env.example listing variable names only. Second, remember the SDKs' documented precedence: ANTHROPIC_API_KEY (even set to an empty string) shadows profiles and federation entirely. A stale variable in a forgotten .env is the most common reason "the SDK is using the wrong credentials" — unset it rather than blanking it, and use ant auth status to see which source actually won.
Named profiles for humans who switch environments
Env vars suit processes; profiles suit people. The SDKs and the ant CLI share an on-disk profile system under $ANTHROPIC_CONFIG_DIR (default ~/.config/anthropic): non-secret settings such as base_url, organization_id, and workspace_id live in configs/<profile>.json, cached credentials in credentials/<profile>.json with file mode 0600. A developer who touches several environments logs in once per profile — ant auth login --profile staging --workspace-id wrkspc_01... — and switches with ANTHROPIC_PROFILE=staging, a per-command --profile flag, or ant profile activate. Claude Code and the Claude Agent SDK honor the same resolution order, so one profile setup serves the whole toolchain.
workspace_id in the profile and no stray export can redirect a developer's traffic.Staging and production: no secrets on disk
Anthropic's own recommendation splits by environment type: API keys for local development, prototyping, and scripts; Workload Identity Federation for production workloads on cloud platforms, CI/CD, and Kubernetes. Where static keys are unavoidable, store them in a secrets manager and inject them into the environment at deploy time, never bake them into images or code. Keys have no expiry, so rotation discipline is on you — per-environment workspaces are what make that rotation safe to do one environment at a time.
Where to go next
See the full env var list for the complete precedence order, injecting credentials into CI/CD for pipeline specifics, and the adoption checklist for the broader rollout picture.