Claude Code API key: where it's stored and how to set it

Claude Code takes an Anthropic API key from the ANTHROPIC_API_KEY environment variable, from an apiKeyHelper script, or from a Console sign-in with /login. On a Mac, a key from /login goes into the macOS Keychain. The other two keep it wherever you put it, which is often a plain text file. Set the variable while you're signed in with a Claude plan and, once you approve it, Claude Code bills the key instead of your subscription.

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

MethodWhere the key livesGood for
/login with a Console accountThe macOS Keychain. If it's locked, over SSH for example, this sign-in failsYour own Mac
export ANTHROPIC_API_KEY=...Your shell, and the file you exported it from, often ~/.zshrcScripts and claude -p
env in a settings filePlain text in settings.json or settings.local.jsonRarely the right place for a key
apiKeyHelperWherever the helper reads it from, such as the KeychainKeeping 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:

  1. Cloud provider credentials, when CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX or CLAUDE_CODE_USE_FOUNDRY is set
  2. ANTHROPIC_AUTH_TOKEN, for gateways and proxies
  3. ANTHROPIC_API_KEY
  4. The apiKeyHelper output
  5. CLAUDE_CODE_OAUTH_TOKEN, from claude setup-token
  6. Anthropic profiles and federation credentials
  7. 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 -w

Then 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=1

Where 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.