How to use Claude Code with an API key instead of a subscription

Can you use Claude Code with an API key?

Yes. Claude Code authenticates in several ways, and two matter for most builders: a claude.ai subscription login and an Anthropic API key from the Claude Console. They bill differently. The facts below are from the authentication and costs pages of the Claude Code docs, checked in October 2026.

For plan names and what they cost today, see the Claude Code pricing guide and the usage limits guide. This page sticks to credentials.

How do you set up Claude Code with an API key?

Create a key in the Claude Console (platform.claude.com), then give it to Claude Code through an environment variable. Install Claude Code first if you have not; the install guide has the steps.

# 1. Put your Console key in the environment for this shell
export ANTHROPIC_API_KEY=your-key-here

# 2. Start Claude Code in your project
claude

# 3. Confirm which credential is active
/status

In an interactive session Claude Code asks once whether to approve the key, and remembers your answer. To change it later, use the “Use custom API key” toggle in /config, which appears only while ANTHROPIC_API_KEY is set. In non-interactive mode with -p, the key is always used when present. To make the variable permanent, add the export line to your shell profile. Never paste a real key into a file you commit.

The same variable works in scripts and CI. Bare mode, which skips local configuration for faster scripted starts, never reads your subscription login. Set ANTHROPIC_API_KEY or supply an apiKeyHelper in the --settings JSON.

Can you sign in with a Console account instead of pasting a key?

Yes. At the /login prompt choose the Anthropic Console account. Your Console admin must have invited you first. From Claude Code v2.1.242, Claude Code then asks how you want to sign in:

• Sign in with your Console account, labeled recommended. Claude Code keeps the OAuth token from that sign-in as an Anthropic profile and creates no API key. It refreshes the login automatically, and if refresh fails requests error until you sign in again.
• Create an API key, labeled legacy. Claude Code creates a Console key for you and stores it with your other credentials.

Some setups skip the question and create a key without asking, for example when you run against a cloud provider such as Amazon Bedrock, or when a settings file sets forceLoginOrgUUID. Unset ANTHROPIC_API_KEY before you sign in without a key. Running /logout removes and revokes the credential that sign-in wrote.

When you first authenticate with a Console account, a workspace called Claude Code is created automatically. It gives your organization central cost tracking for Claude Code. You cannot create API keys for that workspace, and its traffic counts toward your organization's overall rate limits. You can set a workspace spend limit and a workspace rate limit from the Console.

Which credential does Claude Code use when you have several?

When more than one is present, Claude Code chooses in this order, as listed in the docs:

1. Cloud provider credentials, when CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX or CLAUDE_CODE_USE_FOUNDRY is set.
2. The ANTHROPIC_AUTH_TOKEN variable, sent as a bearer token. Meant for LLM gateways and proxies.
3. The ANTHROPIC_API_KEY variable, sent as the X-Api-Key header.
4. The output of an apiKeyHelper script, for dynamic or rotating credentials such as short-lived tokens from a vault.
5. The CLAUDE_CODE_OAUTH_TOKEN variable, a long-lived subscription token for CI and scripts, generated with claude setup-token.
6. Anthropic profile and federation credentials.
7. Subscription OAuth credentials from /login, the default for Pro, Max, Ultra, Team and Enterprise users.

A signed-in Claude apps gateway session sits outside this list and outranks the providers.

Which environment variables matter for API key use?

To keep two accounts apart, such as work and personal, give each its own configuration directory with an alias like alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'. Each directory has its own settings, session history, and claude.ai login or API key.

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

Claude Code runs that command through the system shell and sends its output as both the X-Api-Key and Authorization: Bearer headers. If the script takes longer than 10 seconds, Claude Code shows a slow-helper notice, and if it fails, requests error within three attempts. Credentials from /login are stored in the macOS Keychain, or in a file in your Claude folder with restricted permissions on Linux.

How do billing and spend tracking differ with a key?

Claude Code charges by API token consumption when you use a key. The cost depends on the model, codebase size, how many sessions run at once and any automation. The Session block at the top of /usage shows token usage for the current session, and the docs say it is meant for API users. Claude Code computes the dollar figure locally from token counts at list price, so treat it as an estimate. The authoritative number is the Usage page in the Claude Console. These totals reset when /clear starts a new session.

On a subscription the same session figure is not relevant for billing, because usage is included in the plan. Subscribers see plan usage bars and a breakdown of what counts against their limits instead.

• Pick the model deliberately. A smaller model costs less on routine work. See which model for which job.
• Clear between tasks. Every request sends the whole conversation, and the cache is only five minutes on a key. See the context window guide.
• Set a spend limit. Console workspaces let you cap Claude Code spend. Admins can also set a workspace rate limit to protect other workloads.
• Cap automated runs. In scripts and the GitHub Action use turn limits and timeouts; see the GitHub Actions guide.

Should you use a subscription or an API key?

If you have a long-lived subscription token and want to run Claude in CI, claude setup-token prints a one-year OAuth token after browser approval. It does not save it; you copy it into CLAUDE_CODE_OAUTH_TOKEN. It requires a Pro, Max, Ultra, Team or Enterprise plan and can only make model requests.

Once you are signed in, a good first thing to do with Claude Code is build something small. The board has ideas with ready build prompts, or you can post one you will not build yourself.

How do you keep your API key safe?

• Never commit it. In GitHub Actions use repository secrets and reference them as secrets in the workflow.
• Keep it out of shared settings. A project's .claude/settings.json is meant to be committed. Use your shell profile, a secret manager or apiKeyHelper instead.
• Deny Claude access to env files. Add Read(./.env) to permissions.deny. See the permissions guide.
• Delete retired keys in the Console. Deleting a GitHub secret does not revoke the credential it held.
• Run /logout on shared machines. It removes and revokes the credential a Console sign-in wrote.