API Configuration: Subscription Login vs API Key, How to Choose, How to Switch

📚 Series Navigation: The previous article 03 · How it Works took apart the agentic loop—how Claude Code "Thinks → Acts → Observes". This article solves the prerequisite for it to run: what identity to use to connect to the model. The next article discusses connecting to third-party / domestic models.

In June 2026, the official Claude Code documentation listed a full 6 authentication methods, from subscription login to cloud provider credentials, prioritized layer by layer.

There is a very common pitfall here, one I fell into myself. I wanted to save trouble in the early days and exported an ANTHROPIC_API_KEY in .zshrc. Later I bought a Max subscription, logged in properly with /login, but one day looking at the Console bill, I found the API was continuously deducting money—even though I thought I had always been using my subscription quota. After investigating for a long time I finally understood: as long as there is an API key in the environment, its priority overrides the subscription.

Simply put, "logged in" does not equal "using the right identity". This article will explain this matter thoroughly.

After reading this article, you will get:

• A applicable scenario comparison table for Subscription Login vs API key two paths, to know which path you should take
• Three implementation postures ("where to configure, how to change") for command line login / environment variables / settings.json, and the differences between Mac / Windows / Linux
• A set of self-check commands: use /status to confirm "which identity, which model am I actually using right now," and never be confusedly charged again

---

01 Two Identities: Subscription Login vs API Key

Conclusion first: Individuals using it for themselves, choose subscription login; only when embedding into scripts / CI / team paying by usage, use an API key.

Claude Code connecting to the model essentially answers one question: "On what basis let me use it?" This is authentication—you have to prove who you are and whose quota you are using. The officially supported methods are several, but for beginners, grasping the most mainstream two paths is enough.

Analogy: Entering a gym. Subscription login is like getting a monthly pass—scan face to enter, work out freely within a month, not billed per visit; an API key is like a per-visit ticket—deduct one ticket per entry, pay as you go. The monthly pass is suitable for those who go every day, the ticket is suitable for occasionally visiting once, or bringing a friend in (scripts, automation).

The difference between the two paths, clarified in one table:

Dimension	Subscription Login (Claude.ai account)	API Key (Console / Env Var)
How to connect	Run claude in terminal, browser login	Configure ANTHROPIC_API_KEY env var
How it's billed	Monthly subscription (Pro / Max / Team)	By token usage, deducted from Console balance
Quota	Has usage limits, hit the top wait for refresh	Top up how much you use, no fixed limit
Who it's for	Personal daily interactive development	Scripts / CI / Team pay-as-you-go
Where credentials come from	/login browser authorization	Claude Console create key
Browserless capable?	Needs browser by default (CI uses setup-token)	Yes, pure environment variables suffice

The subscription side is further subdivided, as it will be used later when choosing models:

• Claude Pro / Max: Personal subscription, log in with Claude.ai account. Pro is lightweight, Max has a large quota, can use the strongest model.
• Claude for Teams / Enterprise: Team plans, administrator invites you, unified billing. Enterprise can also configure SSO, managed policies.

For personal projects always go with Max subscription login, worry-free, no need to stare at the balance; only when stuffing automated tasks into GitHub Actions, do you separately get an API key (the specific CI gameplay will be discussed in article 44). Don't touch API keys for daily development, it's just looking for billing anxiety.

💡 One-sentence summary: Subscription = monthly pass (personal daily), API key = ticket (scripts/team pay-as-you-go), first think clearly which kind of person you are, then configure.

---

02 Subscription Login: The Most Worry-Free Path

If you are a personal user, and bought Pro or Max, then this configuration matter basically needs no configuration—just run it and log in.

The operation is just one step. After installing Claude Code (see Article 02 for installation), type in the terminal:

claude

Upon first launch, Claude Code will automatically open the browser for you to log into your Claude.ai account. After logging in, the browser will jump back to the terminal, done.

A few real situations you might bump into, mentioned in advance:

• Browser didn't pop up automatically? Press c in the Claude Code interface, it will copy the login link to the clipboard, you paste it into the browser yourself to open.
• Browser gave a string of "login code" after login, didn't jump back? Paste that string of code back to the terminal's Paste code here if prompted prompt. This situation is common in WSL2, SSH remote sessions, containers—because the browser cannot connect back to the local machine's callback port.
• Want to switch accounts / log out? Enter /logout in Claude Code, and re-login on the next launch.

Where are the logged-in credentials stored? This differs by platform, knowing it helps avoid blindness when troubleshooting:

Platform	Credential Storage Location
macOS	Encrypted system Keychain
Linux	~/.claude/.credentials.json (Permission 0600)
Windows	%USERPROFILE%\.claude\.credentials.json (Inherits user directory permissions)

These are all automatically managed by Claude Code through /login / /logout, you don't need to touch them manually. When I was troubleshooting login issues on Mac, I followed the Linux path and looked for ~/.claude/.credentials.json, but couldn't find it no matter what, and even suspected the login failed—the reason was right here: macOS doesn't put it in a file at all, but stuffs it into the Keychain.

💡 One-sentence summary: Subscription users "run claude → browser login" and it's all set, credentials are automatically stored by Claude Code, don't manually go looking for them.

---

03 API Key: The Path for Scripts and Teams

The API key path, its applicability is actually very narrow—if you don't do automation, and are not in a team paying by usage, you basically won't need it. But since we need to explain clearly "how to switch," you must first know what it looks like.

Step one, get the key. Go to Claude Console to create an API key (this is Anthropic's official developer console, billed by token usage, which is a separate ledger from the Claude.ai subscription).

Step two, configure as environment variable. Platform commands are different, separated:

macOS / Linux:

export ANTHROPIC_API_KEY=sk-ant-your-key

Windows (PowerShell, permanently write into user environment variables):

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-your-key", [EnvironmentVariableTarget]::User)

⚠️ The key is money, don't put it randomly. Do not write the key into code, commit it to Git, or paste it into any file that will be shared. Using export to set it temporarily in the current terminal is the safest, it's gone when closed. To persist it, go through the system environment variables, do not hardcode it into the project.

Step three, launch confirmation. After setting it up run claude, in interactive mode the system will prompt you to approve once for this key (approve / reject choose one, the choice will be remembered). After approval, it will use it to run.

Here is a critical behavior explicitly stated by the official, which is the root of the pitfall at the beginning:

If you have an active Claude subscription, but also have ANTHROPIC_API_KEY set in the environment, then the API key will take precedence after approval. If this key belongs to a disabled or expired organization, it will directly lead to authentication failure.

In other words, the API key will "override" your subscription. Therefore, we have the switching problem to discuss in the next section.

💡 One-sentence summary: API key follows Console to get key → configure environment variable → launch approval three steps; remember that once it exists it takes priority over the subscription, this is the root of all subsequent "switching" problems.

---

04 How to Switch: Priority is the Truth

Core conclusion: What you "think you are using" doesn't matter, Claude Code's priority order has the final say. To switch, the essence is to touch this priority.

Analogy: The wiring order of sockets. Your wall has several sockets (subscription, API key, cloud credentials...), from which socket the appliance actually draws power, does not depend on which one you want to use in your mind, but looks at which one is actually plugged in, whose position is further ahead. To change the power source, you must unplug the one further ahead.

The authentication priority given by the official documentation, 6 layers from high to low (the higher ones override the lower ones):

Priority	Credential Source	Typical Scenario
1 (Highest)	Cloud Provider (Bedrock / Vertex / Foundry)	Enterprises using cloud vendors
2	ANTHROPIC_AUTH_TOKEN Env Var	Going through LLM gateway / proxy
3	ANTHROPIC_API_KEY Env Var	Direct connection to Anthropic API
4	apiKeyHelper Script Output	Dynamic / rotated credentials
5	CLAUDE_CODE_OAUTH_TOKEN	Long-term token used in CI
6 (Lowest)	/login Subscription Credential	Personal subscription defaults here

This picture "stands up" the table above: 6 layers of credentials stacked vertically from high to low, Claude Code scans from top to bottom, skips all "empty" layers, stops at the first layer with a "value" and uses it—under personal subscription scenarios, the top 5 layers are empty, thus hitting the subscription login at the bottom.

Do you see it clearly? Subscription is at the bottom. So as long as any layer above has a value, it overrides your subscription. This explains the scenario at the beginning—clearly logged into Max, but burning API money—because the ANTHROPIC_API_KEY at layer 3 is pressing down on the subscription at layer 6.

Then how to switch back to subscription? The method given by the official is very direct—clear the layer with higher priority:

unset ANTHROPIC_API_KEY

Then run /status to confirm. If you temporarily don't want to use a key in interactive mode, you can also go through the "Use custom API key" toggle in /config to turn it off.

Conversely, switching from subscription to API key, is just export the key, and approve it once (see section 03).

A few details easy to step on, noted together:

• ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN only take effect for terminal CLI sessions. Claude Desktop desktop client and remote sessions only recognize OAuth login, and do not read these environment variables.
• Claude Code on the Web (web version) will always use your subscription credentials, the API key environment variable in the sandbox cannot override it.
• ANTHROPIC_AUTH_TOKEN (Layer 2) and ANTHROPIC_API_KEY (Layer 3) are two different things: the former is sent as Authorization: Bearer header, used when going through gateway / proxy; the latter is sent as X-Api-Key header, used when directly connecting to the official API. Don't mix them up.

💡 One-sentence summary: Switching = adjusting priority. Subscription is at the bottom layer, any API key / token in the environment will override it; to switch back to subscription, unset the high-layer one, and verify with /status.

---

05 Model Selection Basics: opus, sonnet or default

Identity is configured, there is one more thing to decide: which model to let it use for work.

Analogy: Assigning work picking people. Opus is the strongest senior engineer in the group—good brain, deep reasoning, but slow and expensive; Sonnet is the mainstay worker—fast and steady for daily programming, high cost-effectiveness; Haiku is the errand boy—replies instantly for simple tasks, most economical. Hard problems to Opus, daily work to Sonnet, chores to Haiku.

Claude Code uses model aliases so you don't have to remember a long version string. These are commonly used:

Alias	Purpose
default	Special value: clear manual overrides, revert to your account tier recommended model
opus	Latest Opus, complex reasoning / architectural decisions
sonnet	Latest Sonnet, daily programming
haiku	Fast and efficient, handles simple tasks
best	Currently equivalent to opus, uses the most powerful available model
opusplan	Mixed mode: Plan Mode uses Opus to think, execution switches to Sonnet to do
opus[1m] / sonnet[1m]	With 1 million token context window, for gnawing large codebases / long sessions

Note: Aliases point to "versions recommended for your tier", and will update over time. Which version they specifically resolve to, refer to the official documentation—for example, on Anthropic API opus currently resolves to Opus 4.8, sonnet resolves to Sonnet 4.6, but different providers (Bedrock / Vertex etc) resolve to different versions (subject to official documentation, may change).

Your subscribed tier determines which model is given to you by default:

Account Type	default resolves to
Max / Team Premium / Enterprise Pay-as-you-go / Anthropic API	Opus 4.8
Pro / Team Standard / Enterprise Subscription Seats	Sonnet 4.6

That is to say, Pro users default to Sonnet, Max users default to Opus—this is also one of the reasons for recommending heavy users to get Max. Additionally, when reaching the Opus usage threshold, Claude Code might automatically fall back to Sonnet, this is normal behavior, not a bug.

How to set the model? The official gives four ways according to priority:

# 1. Temporarily switch during session (running /model without arguments opens picker) — highest priority
/model sonnet

# 2. Specify at launch
claude --model opus

# 3. Environment variable (takes effect for this session)
ANTHROPIC_MODEL=opus

// 4. Write into settings.json, permanently as default for new sessions — lowest priority
{
  "model": "opus"
}

The above are arranged from high to low priority: in-session /model > at launch --model > environment variable ANTHROPIC_MODEL > settings file. A practical habit: daily fix sonnet in settings.json, when encountering architecture problems that need hard gnawing, temporarily /model opus in the chat to step up, saves quota.

Details about effort level (/effort, controlling thinking depth), and opusplan won't be expanded here—getting the model right is enough for beginners. Check the official "Model Configuration" documentation when you need to dig deeper.

💡 One-sentence summary: Hard problems opus, daily sonnet, chores haiku; default follows your subscription tier, Pro defaults to Sonnet, Max defaults to Opus.

---

06 Hands-on: 3 Minutes to Confirm "Who Am I Using"

Reading without practicing is equal to not reading. Run this set of commands once, and you can thoroughly clarify your current identity and model status. The whole process is operated in the terminal, then in the Claude Code interface, without relying on any complex environment.

Step one: Enter Claude Code. Pick any directory, run:

claude

Step two: Check current status. Type in the Claude Code input box:

/status

It will display your account information and the currently active authentication method / model. Expect to see something like (specific fields depend on version, actual display prevails):

Account: your@email.com (Max)
Auth: Claude subscription (OAuth)
Model: opus (Opus 4.8)

If the Auth here shows an API key, and you thought you were using a subscription—congratulations, you just caught the pitfall mentioned at the beginning.

Step three: See what models are available / switch them. Enter:

/model

It will pop up the model selector, listing opus / sonnet / haiku and other options, select up and down, enter to confirm. If you want to switch directly:

/model sonnet

Step four (optional): Verify the priority of "Subscription vs API Key". This step lets you see with your own eyes the rule discussed in section 04. First exit Claude Code, in the terminal:

# See if there is an API key in the environment "secretly" overriding your subscription
echo $ANTHROPIC_API_KEY

• If it outputs a string like sk-ant-...: It means it is overriding your subscription. To use the subscription again, unset ANTHROPIC_API_KEY, enter claude again and run /status to re-check, Auth should change back to subscription.
• If output is empty: You were already on the subscription (or other higher priority credentials), no problem.

Windows (PowerShell) checks environment variables using:

echo $env:ANTHROPIC_API_KEY

Acceptance criteria: You can use /status to state at a glance "Am I using a subscription or API key right now, which model am I running," and you can manually switch back to the subscription through unset + re-check. If you can do this, the core goal of this article is achieved.

---

07 Summary

This article explained one thing clearly: What identity Claude Code uses to connect to the model, and how to choose and switch this identity.

Your Situation	How to Configure	Default Model
Personal Pro / Max	Run claude → browser /login	Pro→Sonnet, Max→Opus
Scripts / CI / Team Pay-as-you-go	Console get key → Configure ANTHROPIC_API_KEY	Depends on specific setting
Want to switch back to subscription	unset ANTHROPIC_API_KEY + /status re-check	—

Three most important points to remember:

• Subscription is at the lowest priority layer, any API key / token in the environment will override it—check this first if inexplicably charged.
• /status is your magic mirror: If you don't know who you are using, type it.
• Pick models according to the job: Hard problems opus, daily sonnet, default follows subscription tier.

You should now be able to: correctly log in after installation, understand which identity and model you are using, switch back and forth between subscription and API key, and no longer fall into the pit of "clearly logged into subscription but charged API fees".

Next Article Preview

Up to here, what you connected to are still Claude's official models. But when using Claude domestically, the official API is not considered friendly—can Claude Code be made to run DeepSeek, Qwen, GLM and other domestic models?

Yes. The secret lies in the environment variable that kept appearing in this article but was never expanded upon—ANTHROPIC_BASE_URL: it doesn't change "which model to use", it only changes "where the request is sent". The next article 05 · Accessing Third-Party / Domestic Models, will use it to connect Claude Code to domestic large models, saving money and eliminating the need for proxies.

Leaving you a small thought: Since the API key overrides the subscription, if we point ANTHROPIC_BASE_URL to a domestic platform, and configure the corresponding key, does Claude Code get a "heart transplant"? Find out in the next article.

---

Having connected the "main road" of the official model, next article let's turn into the "side road" of domestic models.

---

Recommended Reading

• MCP: Connect Claude to the External World
• Control and Modes: The "Mixing Console" in Your Hand When Opening a Session
• Plugins Reference: Package Your Configurations into a Shareable Bundle