TL;DR

Claude Code supports 6 different authentication methods with a strict priority order. Get the order wrong and your Pro subscription silently gets overridden by an API key, costing you real money.

I built claude-auth-setup — a cross-platform installer (Bash + Batch + PowerShell) that handles the whole thing correctly. MIT licensed, ~17KB of bash, zero runtime dependencies.

This post walks through the design decisions, the cross-platform tax, and the testing approach.

The Problem

The Claude Code auth resolution order, highest to lowest:

Cloud provider creds (Bedrock / Vertex AI / Foundry)

ANTHROPIC_AUTH_TOKEN

ANTHROPIC_API_KEY ← the silent footgun

apiKeyHelper script

CLAUDE_CODE_OAUTH_TOKEN

Subscription OAuth ← what most users actually want

If you're a Pro/Max subscriber and you ever set ANTHROPIC_API_KEY to test something — the API key wins forever until you explicitly unset it. No error. No warning.…