Claude Code API key: when to use one, how to set it, and how to switch back

A Claude Code API key is a Claude Console key that you hand to Claude Code through the ANTHROPIC_API_KEY environment variable or an apiKeyHelper script, so usage is billed per token to your Console account instead of drawing from a Pro or Max subscription. You don't need one if you have a paid Claude plan: logging in with /login is the default, and an API key only makes sense when you want pay-as-you-go billing, automation, or a company-managed key.

This guide covers when each option fits, how to set a key, how Claude Code picks between credentials, and how to switch back. It is based on the official authentication docs, the settings reference and Anthropic's help center, read on 26 October 2026.

API key or subscription login: which should you use?

Claude Code accepts several account types. According to the setup docs, it "requires a Pro, Max, Team, Enterprise, or Console account," and the free claude.ai plan does not include it. Cloud providers such as Amazon Bedrock are a separate route, covered in the Bedrock and Vertex guide.

As of October 2026, the Claude pricing page lists Pro at $17 per month billed annually or $20 billed monthly, with Max from $100 per month. Token prices for API use are on the same page. Which is cheaper depends on how much you use Claude Code; the Claude Code pricing guide and the cost guide go deeper.

How do you get an API key for Claude Code?

Keys come from the Claude Console. For a personal account, create a key in your Console settings. For an organization, the authentication docs describe this flow:

1. An admin invites you from the Console's Members page, or sets up SSO.
2. The admin assigns a role. The Claude Code role can only create Claude Code API keys. The Developer role can create any kind of API key.
3. You accept the invite, install Claude Code, and log in with your Console credentials.

You can also skip the manual key. From the shell, claude auth login --console signs you in with your Console account for API billing. If you pick the Console account at the /login prompt on v2.1.242 or later, Claude Code offers two routes: Sign in with your Console account, labeled recommended, which stores an OAuth login and creates no API key, and Create an API key, labeled legacy, which creates a Console key and stores it with your other credentials.

The costs docs add one detail worth knowing: "When you first authenticate Claude Code with your Claude Console account, a workspace called "Claude Code" is automatically created for you." Admins can set workspace spend limits and rate limits on it.

How do you set ANTHROPIC_API_KEY?

Export the key in the shell where you start Claude Code:

# macOS, Linux, WSL: current shell only
export ANTHROPIC_API_KEY=sk-ant-...
claude

# Windows PowerShell: current session only
$env:ANTHROPIC_API_KEY = "sk-ant-..."
claude

To make it permanent, add the export line to your shell config file, such as ~/.zshrc, or add a user environment variable in Windows settings, then open a new terminal. Anthropic's help article on managing API key environment variables recommends setting the key only for the sessions that need it if you also have a subscription.

What happens next depends on the mode:

• Interactive sessions: Claude Code asks you once whether to use the key and remembers your answer. To change it later, use the "Use custom API key" toggle in /config, which only appears while ANTHROPIC_API_KEY is set.
• Non-interactive mode (-p): the key is always used when present, with no prompt.

Run /status inside Claude Code to see which credential is active. When a login and an API key are both configured, /status marks the one that isn't in use. From a script, claude auth status prints JSON whose authMethod field reads api_key when a key is in use.

How does Claude Code choose between an API key and a login?

When several credentials exist, the authentication precedence list decides. In order:

1. Cloud provider credentials, when CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX or CLAUDE_CODE_USE_FOUNDRY is set
2. ANTHROPIC_AUTH_TOKEN, sent as an Authorization: Bearer header, mainly for LLM gateways
3. ANTHROPIC_API_KEY, sent as the X-Api-Key header
4. apiKeyHelper script output
5. CLAUDE_CODE_OAUTH_TOKEN, a long-lived token from claude setup-token
6. Anthropic profile and federation credentials
7. Subscription OAuth credentials from /login

The practical consequence: an approved API key beats your subscription login. The docs warn that this "can cause authentication failures if the key belongs to a disabled or expired organization," which is the usual cause of the This organization has been disabled error. The login troubleshooting guide covers that and other auth errors.

How do you use apiKeyHelper for rotating keys?

apiKeyHelper is a setting that runs your own command and uses its output as the credential. It suits keys that expire, such as short-lived tokens fetched from a vault:

{
  "apiKeyHelper": "/bin/generate_temp_api_key.sh"
}

Key facts from the settings reference:

• Claude Code runs the command through /bin/sh on macOS and Linux and cmd on Windows, and sends the output as both the X-Api-Key and Authorization: Bearer headers.
• It caches the value for five minutes by default. Change that with CLAUDE_CODE_API_KEY_HELPER_TTL_MS.
• It reruns the command when a request fails with 401 or 403, and, on v2.1.246 or later, before a request when the cached output is an expired JWT.
• When the command comes from project or local settings, an interactive session doesn't run it until you accept the workspace trust prompt.
• If the helper takes longer than 10 seconds, a notice in the prompt bar shows the elapsed time.

The script must print only the key to stdout and exit with code 0. If it fails, prints nothing, or prints extra text such as a log line, requests fail with Your apiKeyHelper script is failing. Running /login won't help while the setting is present, because the helper ranks above a saved login. Test the script by running it directly in your shell.

How does billing differ with an API key?

With a key, you pay per token at API rates, separate from any Claude plan. Anthropic's article on using Claude Code with a Pro or Max plan says that when the variable is set, Claude Code "will use this API key for authentication instead of your Claude subscription," which means API usage charges instead of your plan's included usage. A few related points:

• /usage shows a cost estimate computed locally at list price. For authoritative numbers, the costs docs point to the Console usage page.
• Usage credits for going past plan limits are managed with /usage-credits, which isn't available with API key authentication.
• Max and Team plans include monthly API credits, but the help article on those credits states: "They don't cover interactive Claude Code sessions or extra usage after you hit your plan's limits."
• API key traffic is metered per token against your Console organization, which has its own API rate limits, rather than drawing from a plan's five-hour and weekly limits. The cost guide covers workspace spend limits.

How do you switch from an API key back to your subscription?

Remove the key, then confirm:

unset ANTHROPIC_API_KEY      # macOS, Linux, WSL
claude

In PowerShell, run Remove-Item Env:ANTHROPIC_API_KEY. Then delete any export ANTHROPIC_API_KEY=... line from ~/.zshrc, ~/.bashrc or ~/.profile, or from your PowerShell profile and Windows user variables. Run /status to check that your subscription is the active method.

If the key keeps coming back, look for tools that load it silently. The error reference notes that direnv, dotenv shell plugins and IDE terminals can load a stale key from a project .env file. Run env | grep ANTHROPIC in the same shell to find it.

If you logged in through a Console account rather than an environment variable, run /login and choose your Claude subscription. If you want Claude Code to stop offering API credits when you reach your plan's limits, Anthropic's help center suggests running claude logout, then logging in again with only your Pro or Max plan credentials.

Keeping keys and setup notes in one place

Treat the key like a password: keep it in a secrets manager or your CI's secret store, never in a committed settings file. The steps around it, such as which variables a project needs and how to check /status, are worth writing down once. Kipt stores prompts and Agent Skills as Markdown in a private GitHub repo you own, so a setup checklist prompt with a {{project_name}} blank is easy to find with Cmd+K next time.

For where settings files live and how the env block works, see the settings guide.