Claude Code API key: where it's stored and how to set it
By Maria Otworowska,
We make fidelius, a Mac app built on iCloud Keychain, with no vault or sync of its own, that keeps API keys out of shell and project files. It comes up at the end; everything before that works without it.
Getting a key
API keys come from the Claude Console at platform.claude.com, under API keys. They bill per token to the Console organization that owns them, separately from a Claude Pro, Max, Ultra, Team or Enterprise plan. If you have a plan, you may not need a key at all: /login with your claude.ai account uses the subscription.
The ways to give Claude Code a key
| Method | Where the key lives | Good for |
|---|---|---|
| /login with a Console account | The macOS Keychain. If it's locked, over SSH for example, this sign-in fails | Your own Mac |
| export ANTHROPIC_API_KEY=... | Your shell, and the file you exported it from, often ~/.zshrc | Scripts and claude -p |
| env in a settings file | Plain text in settings.json or settings.local.json | Rarely the right place for a key |
| apiKeyHelper | Wherever the helper reads it from, such as the Keychain | Keeping the key out of every file |
Since v2.1.242, a Console sign-in at /login asks whether to create a key at all. Signing in without one, labeled recommended, stores an OAuth login; creating a key is labeled legacy. A subscription login is stored in the Keychain too, and only that one falls back to ~/.claude/.credentials.json (mode 0600) when the Keychain is locked. The full list of methods is in Claude Code's authentication docs.
Which one wins
When several are set, Claude Code picks the first of these that it finds:
- Cloud provider credentials, when CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX or CLAUDE_CODE_USE_FOUNDRY is set
- ANTHROPIC_AUTH_TOKEN, for gateways and proxies
- ANTHROPIC_API_KEY
- The apiKeyHelper output
- CLAUDE_CODE_OAUTH_TOKEN, from claude setup-token
- Anthropic profiles and federation credentials
- Your subscription login from /login
Number 3 is the one that surprises people. In interactive mode Claude Code asks once whether to use the key and remembers your answer; with claude -p it uses the key without asking. A key left in ~/.zshrc from another project can quietly move your Claude Code usage onto API billing. To check and switch back, delete the export ANTHROPIC_API_KEY line from your shell files, or the key comes back in the next terminal window, then:
$ unset ANTHROPIC_API_KEY$ claude# then run /status inside Claude Code to see which credential is in use
/config has a "Use custom API key" toggle, shown only while the variable is set, if you want to change the remembered answer instead.
Settings files hold the key in plain text
Claude Code reads an env block from its settings files: your user file at ~/.claude/settings.json, the project's .claude/settings.json, which is meant to be committed, and .claude/settings.local.json, which isn't. A key put there is plain text, and the settings reference notes that env values reach every subprocess Claude Code starts. Local settings files have leaked to GitHub in large numbers, which we covered in does Claude Code save passwords in settings.local.json?
Keep the key in the Keychain with apiKeyHelper
apiKeyHelper names a shell command that prints your key. Claude Code runs it when it needs the key, so no file has to hold it. With the macOS security command, store the key once. With -w last it prompts for the value, so the key doesn't end up in your shell history:
$ security add-generic-password -a "$USER" -s anthropic-api-key -wThen point Claude Code at it in ~/.claude/settings.json:
{
"apiKeyHelper": "security find-generic-password -s anthropic-api-key -w"
}Make sure ANTHROPIC_API_KEY isn't set too, or it wins over the helper. The helper in turn ranks above a subscription login, so while it's set, Claude Code bills the key. The first time the helper runs, macOS may ask whether security can read the item; choose Always Allow if you don't want the prompt again.
The commands Claude Code runs can see the key
A variable exported in your shell is passed to claude, and from there to every command it runs for you. One env or printenv in a session prints the key into the conversation. Claude Code has a switch that helps: CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 strips variables that look like credentials, by name or by value, from the environment of the Bash commands, hooks and stdio MCP servers it starts, according to its environment variable reference. It leaves GitHub tokens and proxy settings in place, and it's one layer, not a guarantee. Keys that never reach Claude Code's environment are the safer kind.
$ export CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1Where fidelius fits
fidelius keeps your project API keys in the Keychain, grouped by project, so none of them has to sit in ~/.zshrc or a .env file, and Claude Code starts without them. With one click it adds instructions telling Claude Code to run commands that need a key through accio, as in accio myapp npm test. The key goes to that command, and Claude Code works with the key name, as long as it follows those instructions. When accio sees Claude Code, it also masks key values in command output, which catches accidents.