Authentication, Plans & Access

Installing Claude Code is the easy part. The thing that actually decides whether you can run it — and whose usage you spend — is authentication: which identity Claude Code presents when it calls Anthropic.

There are two billing worlds, and you pick one:

• Subscription (OAuth) — you log in with your Claude.ai account (Pro, Max, Team, or Enterprise). Usage counts against your plan's limits. This is what most individual developers want.
• API (pay-as-you-go) — you authenticate with a key from the Claude Console and pay per token. This suits teams that already bill through the API, or anyone who wants metered, per-token cost.

The single most important fact: Claude Code is not on the free tier. A free Claude.ai account cannot run it at all. You need Pro, Max, Team, Enterprise, or a Console (API) account.

The second most important fact: when several credentials exist on one machine, Claude Code follows a strict precedence order to decide which one wins. Most "why is it billing the wrong thing?" confusion comes from not knowing that order — so we'll make it concrete.

There are three entry points to authentication. Pick whichever fits your situation.

1. Browser login (the default). Run claude in any project directory. On first launch it opens a browser to sign in with your Claude.ai account. If the browser doesn't open, press c to copy the login URL and paste it manually. If sign-in shows you a login code instead of redirecting back, paste that code at the terminal's Paste code here if prompted prompt — this is normal in WSL2, SSH sessions, and containers where the local callback can't be reached.

2. Inside a session. Already running? Type /login to authenticate or switch accounts, and /logout to sign out and re-authenticate.

3. An environment variable. Set ANTHROPIC_API_KEY (a Console key) and Claude Code uses it without any browser flow — handy for scripts and CI, but read the security section first, because this variable has sharp edges.

Claude Code also ships dedicated auth subcommands for scripting:

claude auth login              # browser/OAuth login
claude auth login --console    # log in with Claude Console credentials
claude auth login --email      # email-based login flow
claude auth login --sso        # single sign-on flow
claude auth logout             # sign out
claude auth status             # machine-readable JSON; exit 0 if logged in, 1 if not
claude auth status --text      # human-readable status

Inside a session, /status tells you which authentication method is currently active — the fastest way to confirm you're spending the account you think you are.

When more than one credential is present, Claude Code does not merge or guess — it walks a fixed list top to bottom and uses the first one it finds. Internalize this order and surprise billing disappears.

Read it as a fall-through: if no cloud-provider flag is set, Claude Code checks ANTHROPIC_AUTH_TOKEN; if that's empty it checks ANTHROPIC_API_KEY; and so on down to your subscription login, which is the catch-all default.

Two distinctions trip people up:

• ANTHROPIC_AUTH_TOKEN is not ANTHROPIC_API_KEY. The auth token is a bearer token (Authorization: Bearer …) for gateways; the API key is an Anthropic Console key (X-Api-Key). Different headers, different purposes, different precedence rank.
• A Console API key (step 3) outranks your subscription login (step 6). So if you have both a Pro subscription and ANTHROPIC_API_KEY exported, the API key wins — even though you'd probably rather spend the subscription.

Here's the full landscape so you can pick deliberately. Prices are monthly, per the official pricing page.

How to choose:

• Solo dev, predictable bill? Start with Pro. If you hit limits often, step up to a Max tier — same subscription auth, more headroom. Check claude.com/pricing for current Max usage tiers and prices.
• A team? A Team plan gives you central billing; both Standard and Premium seats include Claude Code, with Premium seats getting more usage per seat.
• You want exact, per-token cost or already bill via the API? Use a Console account with ANTHROPIC_API_KEY. There's no monthly floor — you pay for what you use.

Subscription plans give you bundled, rate-limited usage at a flat price; the API gives you metered, uncapped spend. Neither is "better" — it's flat-rate predictability versus pay-per-use precision.

Two rules and a storage map will keep you out of trouble.

Rule 1 — Never write ANTHROPIC_API_KEY to your shell profile. Putting export ANTHROPIC_API_KEY=sk-... in ~/.zshrc or ~/.bashrc leaks the key into the environment of every child process you ever launch — a broad, persistent exposure. Set it only in the specific shell or CI job that needs it, or better, use a credential helper (below).

Rule 2 — Remember the precedence trap. Because the Console API key (step 3) outranks your subscription (step 6), an ANTHROPIC_API_KEY left lying around will silently hijack your auth. If that key belongs to a disabled or expired org, you get authentication failures even though your subscription is perfectly fine. The fix:

unset ANTHROPIC_API_KEY   # fall back to subscription OAuth

Then run /status to confirm the subscription is now active.

Where credentials actually live:

Claude Code manages this file for you through /login and /logout — you should never hand-edit it. For dynamic or short-lived credentials (e.g. tokens pulled from a vault), use the apiKeyHelper setting: a shell script in settings.json that returns a key on demand. It's called every 5 minutes or on an HTTP 401, with a custom TTL via CLAUDE_CODE_API_KEY_HELPER_TTL_MS; if it takes over 10 seconds, Claude Code warns you.

CI runners have no browser, so OAuth login won't work there. The answer is a long-lived token you generate once and inject as an environment variable.

claude setup-token

This walks you through OAuth authorization and prints a one-year OAuth token to the terminal. It is not saved anywhere — copy it immediately and store it in your CI provider's secret manager (GitHub Actions secrets, etc.). Then expose it to the job:

export CLAUDE_CODE_OAUTH_TOKEN=your-token

That's precedence step 5 — it authenticates against your subscription, so setup-token requires a Pro, Max, Team, or Enterprise plan. The token is scoped to inference only and cannot start Remote Control sessions.

# GitHub Actions — minimal sketch
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL https://claude.ai/install.sh | bash
      - run: claude -p "review the diff" --permission-mode dontAsk
        env:
          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

One sharp edge: CLAUDE_CODE_OAUTH_TOKEN does not work in --bare mode. Bare mode strips the machinery that reads it, so a script using --bare must authenticate with ANTHROPIC_API_KEY or an apiKeyHelper instead.