← All guides

SetupUsage limits

Claude Code BYOK: Can You Bring Your Own API Key (and When Should You)?

By Neo Zino - builder of ClockedCode·Updated October 6, 2026·11 min read

Claude Code takes your own Anthropic API key. Here is the precedence order, how to switch between a key and a Pro or Max login, and when per-token costs less.

Made with DispatchSEO

Yes, Claude Code takes your own Anthropic API key. Export ANTHROPIC_API_KEY, start claude, approve the key when it asks, and every request after that is billed to your API account instead of your Pro or Max plan. The part that trips people up is the order of precedence: a key outranks your subscription login, so a stale one in your shell profile quietly takes over.

TL;DR: ANTHROPIC_API_KEY beats the /login subscription. Claude Code asks once to approve it (-p mode skips the question). To go back, unset ANTHROPIC_API_KEY and confirm with /status. A key costs more than Max for daily heavy use and less for light use. Bedrock, Vertex and Foundry variables outrank both.

Is bringing your own key a real option in Claude Code?

It is, and it is the documented alternative to logging in with a claude.ai account. Claude Code accepts three families of credential: a subscription login (Pro, Max, Team, Enterprise), a Claude Console account or API key, and a cloud provider. The word "BYOK" mostly shows up in search because people compare Claude Code with editors that ask you for a key. Here the key is optional, and the login path is the default.

What changes when you bring a key is who gets the bill and which limits apply:

• Subscription login: a flat monthly price, with five-hour and weekly usage windows as the ceiling.
• API key: per-token billing on a Console account, with no plan windows. Your ceiling is whatever spend limit you set on the Console workspace.

Which one fits depends on how many hours a week you actually run it. The cost section below puts numbers on that. If your real problem is hitting the plan ceiling, check the usage limits checklist first, because switching to a key just swaps a limit you notice for a bill you might not.

Which credential does Claude Code use when you have several?

Claude Code walks a fixed list and uses the first one it finds. This is the order from the official authentication docs:

The consequence worth memorizing: a cloud provider variable beats everything, and ANTHROPIC_API_KEY beats your subscription. The docs say it plainly: with an active subscription and ANTHROPIC_API_KEY set, Claude Code "uses the API key once you approve it", and that can cause authentication failures if the key belongs to a disabled or expired organization.

Two behaviors follow from how the approval works:

• Interactive sessions ask once. You approve or decline the key, and Claude Code remembers the answer. The "Use custom API key" toggle in /config changes it later, and it only appears while the variable is set in your environment.
• claude -p never asks. In non-interactive mode the key is used whenever it is present. A script on a machine that also has your login will bill the key, not the plan.

Cloud sessions are the exception. Claude Code on the web always uses your subscription credentials, and a key set in the cloud environment does not override them.

What claude auth status printed under six setups

The docs describe the order. I wanted to see it, so on 2026-10-06 I ran claude auth status on Claude Code 2.1.290 with a fake key and a throwaway CLAUDE_CONFIG_DIR for each setup. The subcommand prints a small JSON block; these are the fields that mattered.

Reading the table:

• With nothing set it reports "loggedIn": false and "authMethod": "none". A plain claude -p "hi" on that config answered Not logged in · Please run /login.
• A key alone shows "authMethod": "api_key" and "apiKeySource": "ANTHROPIC_API_KEY". That is the line to look for when you are not sure why you are being billed.
• Adding CLAUDE_CODE_USE_BEDROCK=1 flipped the provider to bedrock and the method to third_party even though the key was still exported. The cloud variable won, which matches the first rung of the ladder.
• An apiKeyHelper in settings.json reported api_key_helper, with apiKeySource naming the helper.
• Setting ANTHROPIC_AUTH_TOKEN next to the key changed authMethod to oauth_token. I read that label as the bearer-token path winning, in line with the ladder, but it is the label the tool prints and not something the docs spell out.

One more result that is easy to miss: a key is not validated when you set it. claude auth status happily reported a fake key as logged in, and claude -p "hi" with that key produced no output and no error until my 90-second timeout killed it. A mistyped key looks like a hang, not a rejection. If a scripted run stalls with a key set, test the key with a direct API call before blaming Claude Code.

How do you switch between a key and your subscription?

Switching is mostly about the environment variable, not about /login.

To use your key:

export ANTHROPIC_API_KEY=sk-ant-...
claude

Approve the prompt. Put the export in your shell profile only if you want it every time, and keep the key out of any committed settings file. The env block of ~/.claude/settings.json works, as does .claude/settings.local.json; the project-level .claude/settings.json is the one that gets committed, so a key there ends up in git. The settings.json generator writes a valid file if you would rather not hand-edit it.

To go back to your subscription:

unset ANTHROPIC_API_KEY
claude

Then run /status. When a login and a key are both configured, it marks the credential that is not in use. If you want to be sure the login itself is healthy, /logout followed by /login re-authenticates; logging out also resets first-launch setup, so expect the walkthrough again.

To run both side by side: give each account its own configuration directory. The docs' pattern is an alias such as alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'. Each directory keeps its own settings, session history and credential, so a key in one never leaks into the other.

For scripts and CI there is a third option that is neither of these. claude setup-token prints a one-year OAuth token tied to your subscription, which you export as CLAUDE_CODE_OAUTH_TOKEN. It needs a Pro, Max, Team or Enterprise plan, so it does not help if you want per-token billing. Use ANTHROPIC_API_KEY or an apiKeyHelper there instead. If you have not installed the CLI yet, start with the install guide.

Does a key cost more than a plan?

For steady daily use, usually yes. Anthropic's cost docs give the enterprise average as about $13 per developer per active day and $150 to $250 per developer per month, with 90% of users under $30 per active day. Claude Code's own /usage figure is computed locally at list price, so treat it as an estimate and check the Console usage page for the real number.

The worked session in that figure is plain arithmetic on the published per-million-token rates, not a measured bill. A long session with 200,000 fresh input tokens, 3 million cache-read tokens and 60,000 output tokens costs about $1.60 on Sonnet 5.5 and about $2.60 on Opus 5.5. Two things the arithmetic hides:

• Cache reads dominate long sessions. Claude Code re-sends the whole conversation on every turn, and cached reads are cheap per token but there are millions of them. Clearing context between tasks cuts the bill on both billing models.
• Cache lifetime differs. On a subscription the prompt cache lasts an hour; on an API key it is five minutes by default. A coffee break means the next message reprocesses your full context at the uncached rate.

So the rough rule: if you run Claude Code for hours most weekdays, a Max plan is usually cheaper than the key, and a Pro plan covers lighter use. If you use it a few evenings a month, or you want a hard dollar cap, or you are billing a client for the exact usage, the key is the better fit. Model choice moves the numbers more than the billing model does; Opus 5.5 output is twice the price of Sonnet 5.5 output, which is why the Opus 5 breakdown matters if you pay per token.

What about Bedrock, Vertex, Foundry and gateways?

Those are the other "bring your own" routes, and they are for organizations that already buy Claude through a cloud account. You set CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX or CLAUDE_CODE_USE_FOUNDRY, and Claude Code authenticates with your cloud credentials. No Anthropic login is involved, and the bill arrives from AWS, Google Cloud or Azure. Running claude and choosing 3rd-party platform at the login prompt starts a setup wizard for Bedrock and Vertex.

An LLM gateway is a different thing again: ANTHROPIC_BASE_URL changes where requests go, and ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY carries the gateway's credential. That is covered in the Claude Code proxy guide, including why a base URL alone does not switch your billing.

Teams on cloud providers lose one thing: Claude Code does not send metrics back to Anthropic from those setups, so the Anthropic analytics dashboards do not cover the usage. Per-user attribution needs OpenTelemetry or a gateway.

When a key is the wrong call

• You live in Claude Code all day. The per-token bill will probably pass the price of Max. Compare against your real /usage numbers for a week before deciding.
• You want predictable spending without setting limits. A subscription caps you with a usage window. A key caps you only if you set a Console workspace spend limit, and a runaway loop or an agent team can burn through budget quickly.
• You want usage credits or plan-tied features. The /usage-credits command is not available with API key authentication, and a key does not unlock anything a subscription lacks.
• You are on a managed machine. An administrator can block ANTHROPIC_API_KEY outright with forceLoginMethod or forceLoginOrgUUID, and Claude Code then refuses to start with the key set.
• You mainly want a different model. A key still means Claude models. Pointing Claude Code at other vendors' models through a translation layer is unsupported.

If you do go the key route and want the rest of the setup sorted in one paste, with permissions, hooks and a tuned CLAUDE.md, that is what ClockedCode's master prompt is for.

FAQ

Does Claude Code support bring your own key?

Yes. Set ANTHROPIC_API_KEY to a key from the Claude Console and Claude Code asks you once to approve it, then bills that key per token instead of using your Pro or Max login. In non-interactive mode with -p, the key is used without asking.

Will an API key use up my Pro or Max limits?

No. Once the key is approved, requests are billed to the API account and the plan's usage bars are not touched. Your subscription is still there; it is simply not the active credential until you unset the variable.

Why is Claude Code charging my API key when I have a subscription?

An ANTHROPIC_API_KEY left in your shell profile or a settings env block outranks the subscription login once you approve it. Run unset ANTHROPIC_API_KEY and check /status to confirm which method is active.

Can I use a Claude Code API key and a subscription on different machines?

Yes. Credentials are per machine and per configuration directory, so one laptop can run on a key while another uses a login. To keep both on one machine, give each its own CLAUDE_CONFIG_DIR.

Is the API key cheaper than a Claude Max plan?

Usually not for daily heavy use. Anthropic's own cost docs put the enterprise average at $150 to $250 per developer per month, which is above the starting price of Max. A key wins when your use is light, occasional, or you need a hard spend cap.

Can I use Claude Code with Bedrock or Vertex instead of an Anthropic key?

Yes. Set CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX or CLAUDE_CODE_USE_FOUNDRY and Claude Code authenticates through your cloud account. Those variables outrank every other credential, including an Anthropic key.