CoreCodeBlog

Guides

Claude Code with an API key: setup, apiKeyHelper and API vs subscription

Published · Last checked

Claude Code does not need a Claude subscription. It can authenticate with a Claude Console account, an API key in an environment variable, a bearer token for a gateway, or a script that fetches a key. This page lists those options in the order Claude Code prefers them, shows how to set each one, and covers apiKeyHelper, switching accounts and the VS Code extension. It follows Anthropic's Authentication page and settings reference, checked on November 5, 2026.

Key points
  • To use Claude Code with an API key, set ANTHROPIC_API_KEY and approve the key when Claude Code asks. Once approved, the key is used instead of your Pro, Max, Ultra, Team or Enterprise subscription, even if you are logged in.
  • When several credentials exist, Claude Code picks the first of: cloud provider credentials, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper output, CLAUDE_CODE_OAUTH_TOKEN, then the /login subscription login.
  • apiKeyHelper is a settings.json command that prints a key. Claude Code caches the result for five minutes by default and warns in the prompt bar if the command takes longer than 10 seconds.
  • A relay key goes in ANTHROPIC_AUTH_TOKEN together with ANTHROPIC_BASE_URL, not in ANTHROPIC_API_KEY.

How Claude Code authenticates

Anthropic's authentication page lists these account types: a Claude Pro, Max or Ultra subscription, Claude for Teams or Enterprise, the Claude Console, and cloud providers (Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry). A subscription logs in with a claude.ai account. The Console is the API-billed route. On first launch Claude Code opens a browser to log in, except when you have set ANTHROPIC_API_KEY and approve the key, or you ran claude auth login beforehand.

For the Console, the page describes it as the option for organizations that prefer API-based billing: you use or create a Console account, an admin invites users, and users log in with their Console credentials. At the /login prompt, choose the Anthropic Console account. On Claude Code v2.1.242 or later you can then either sign in with your Console account (labeled recommended, stored as an Anthropic profile, no API key created) or create an API key (labeled legacy).

Use an API key with ANTHROPIC_API_KEY

Create a key in the Console, then export it before starting Claude Code:

export ANTHROPIC_API_KEY=your-key
claude

In interactive mode Claude Code asks once whether to use the key, and remembers your answer. To change it later, use the "Use custom API key" toggle in /config; the toggle only appears while ANTHROPIC_API_KEY is set. In non-interactive mode (-p), the key is always used when present. The variable is sent as the X-Api-Key header.

If you have an active subscription and also have ANTHROPIC_API_KEY set, Claude Code uses the API key once you approve it. This can fail if the key belongs to a disabled or expired organization. To go back to the subscription, run unset ANTHROPIC_API_KEY. Run /status to confirm which credential source Claude Code is actually using.

ANTHROPIC_AUTH_TOKEN, the auth token variable

ANTHROPIC_AUTH_TOKEN is a custom value for the Authorization header, prefixed with Bearer . Anthropic's precedence list says to use it when routing through an LLM gateway or proxy that authenticates with bearer tokens rather than Anthropic API keys. It ranks above ANTHROPIC_API_KEY. For long-lived tokens in CI, Anthropic documents a different variable, CLAUDE_CODE_OAUTH_TOKEN, generated with claude setup-token; it is a claude.ai OAuth token and ranks below the API key and the helper.

Which credential wins

When multiple credentials are present, Claude Code chooses one in this 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 Authorization: Bearer.
  3. ANTHROPIC_API_KEY, sent as X-Api-Key.
  4. apiKeyHelper script output.
  5. CLAUDE_CODE_OAUTH_TOKEN.
  6. Anthropic profile and federation credentials.
  7. Subscription OAuth credentials from /login, the default for Pro, Max, Ultra, Team and Enterprise users.

The list also notes that a signed-in Claude apps gateway session sits outside it and outranks the cloud providers. A saved claude.ai login stays on the machine but is not used while a higher credential is active.

apiKeyHelper

apiKeyHelper runs your own command to produce the credential Claude Code sends with model requests. Claude Code runs it through the system shell (/bin/sh on macOS and Linux, cmd on Windows) and sends the output as both the X-Api-Key and Authorization: Bearer headers. Anthropic suggests it for dynamic or rotating credentials, such as short-lived tokens fetched from a vault. It is a string setting that can go in any settings file:

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

Claude Code caches the value and reruns the command in these cases:

The last two apply only when the helper output is the credential being sent and ANTHROPIC_AUTH_TOKEN is not set. If the command comes from project or local settings, an interactive session does not run it until you accept the workspace trust prompt. Claude Code reloads edits to apiKeyHelper in a running session without a restart.

"apiKeyHelper is taking a while" and helper failures

If apiKeyHelper takes longer than 10 seconds to return a key, Claude Code shows a warning notice in the prompt bar with the elapsed time. Anthropic's advice is to check whether your credential script can be optimized if you see it regularly.

If the script exits with an error, times out, or prints nothing, requests fail with Your apiKeyHelper script is failing within three attempts. The same message appears when the script prints something besides the key, such as a login banner or log line. Run /status to see the script's error output; in non-interactive mode stderr carries the reason, prefixed with apiKeyHelper failed:.

Log out, log in and switch accounts

Type /logout at the Claude Code prompt to log out and re-authenticate. Logging out also resets first-launch setup, so the next claude run walks you through login again. Run /login to sign in with another account. Credentials from /login and /logout are kept in the macOS Keychain, or in ~/.claude/.credentials.json on Linux and Windows (%USERPROFILE%\.claude\.credentials.json).

To stay signed in to two accounts at once, give each its own configuration directory with CLAUDE_CONFIG_DIR. Each directory has its own settings, history and claude.ai login or API key:

alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

Anthropic notes that two Claude Console sign-ins made without an API key are not kept apart by separate directories, because that kind of sign-in is stored outside the configuration directory.

API key or subscription: what changes

A subscription includes usage in the plan. An API key is billed per token. Anthropic's gateway documentation says that while a gateway credential variable or apiKeyHelper is active, requests carry that credential in place of your subscription login, and the subscription's usage limits do not apply to them; the traffic is billed per token to whoever owns the credential. In /usage, the Session block shows API token usage and is intended for API users; subscribers see plan usage bars.

For prices we do not restate them here beyond the per-token figures in our Claude API pricing post: Opus 5.5 is $4 per million input tokens and $20 per million output tokens, Sonnet 5.5 is $2 and $10. To compare cost against a plan, read Claude Code on a subscription, the API or a relay and estimate your own usage with the Claude API cost calculator.

VS Code

Anthropic states that apiKeyHelper, ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN apply to the CLI and the surfaces that wrap it, including the VS Code extension. If you have ANTHROPIC_API_KEY set in your shell but still see the sign-in prompt, VS Code may not have inherited your shell environment. Launch VS Code from a terminal with code ., or sign in with your Claude account instead. Claude Desktop and cloud sessions do not call apiKeyHelper or read these variables; they use OAuth.

For the extension, a settings file is more reliable than the shell, because the extension and the CLI share ~/.claude/settings.json. See the IDE guide for the env block and the Disable Login Prompt option.

Using a relay key

CoreCode is a relay answered by official Claude accounts. Claude Code points at it with ANTHROPIC_BASE_URL=https://corecode.live and the key in ANTHROPIC_AUTH_TOKEN, as shown in the Claude Code setup guide. Do not put it in ANTHROPIC_API_KEY, and do not sign in with a claude.ai account at the same time; if you signed in before, run /logout first. If both ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY are set you may see Auth conflict; the errors page says to remove ANTHROPIC_API_KEY and keep only the token. The general method is in how to set a custom API base URL in Claude Code. Top-ups are in CNY by Alipay or WeChat (¥1 = $1 of credit).

FAQ

How do I use Claude Code with an API key?

Create a key in the Claude Console, run export ANTHROPIC_API_KEY=... and start claude. Approve the key when asked. Or choose the Anthropic Console account at the /login prompt.

Can I use Claude Code without a subscription?

Yes. Anthropic lists the Claude Console and cloud providers as account types alongside the claude.ai subscriptions. A Console API key is billed per token instead of drawing on a plan.

Which wins, ANTHROPIC_API_KEY or my claude.ai login?

The API key, once you approve it. The precedence list puts ANTHROPIC_API_KEY above the /login credential. Run unset ANTHROPIC_API_KEY to use the subscription again.

What is the Claude Code apiKeyHelper setting?

A command in settings.json that prints an API credential. Claude Code caches the output for five minutes by default and reruns it after a 401 or 403. Change the interval with CLAUDE_CODE_API_KEY_HELPER_TTL_MS.

How do I log in to Claude Code with a different account?

Run /logout, then /login. To keep two accounts, start Claude Code with a different CLAUDE_CONFIG_DIR for each.

Sources