Claude Code Authentication: How to Connect Your Anthropic Account

Claude Code authentication setup has two completely separate paths depending on how you pay for Claude. Mixing them up is the single most common reason setup stalls.

If you have a claude.ai subscription, you use OAuth. If you access Claude through the API, you use an API key. Knowing which you have before you run claude the first time saves 20 minutes of troubleshooting.

Key Takeaways

• Two authentication methods exist: OAuth is for claude.ai subscribers (Pro and Max plans). API key authentication is for developers accessing Claude through the Anthropic API directly.
• Mixing up the methods causes most auth errors: Trying OAuth with an API-only account, or an API key with a claude.ai subscription, produces failures with unclear error messages.
• OAuth stores a session token, not credentials: After OAuth completes, Claude Code stores a token locally. You do not need to re-authenticate each session unless the token expires.
• API keys must be set as environment variables: Entering a key at the CLI prompt only lasts for that session. Adding it to .bashrc or .zshrc makes it permanent.
• Post-setup auth errors are almost always token expiry or environment variable issues: Not a problem with Claude Code itself.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

What You Need Before You Authenticate

Claude Code must already be installed before the authentication flow can run. You also need either a claude.ai Pro or Max subscription, or an Anthropic API key. Free claude.ai accounts do not include Claude Code access.

Check your account type before starting. Running the auth flow with the wrong account type will fail immediately.

• Install Claude Code first: If you have not done this yet, install Claude Code first using the complete setup guide, the Mac setup guide for macOS, or the Windows WSL setup guide for Windows.
• claude.ai subscription: You need an active Pro ($20/month) or Max ($100/month) plan. Free accounts will fail at the authorisation step.
• Anthropic API key: Retrieve this from console.anthropic.com. Your account needs active credits for Claude Code to run.
• Internet connection required: The initial OAuth flow cannot complete offline. API key auth also requires a live connection for every Claude Code interaction.
• Linux/WSL browser access: Confirm your terminal can open a browser URL, or be ready to copy-paste the OAuth URL manually.

Claude.ai Subscription vs API Key: Which Should You Use?

Use OAuth if you pay for claude.ai Pro or Max. Use an API key if you access Claude through the Anthropic API at console.anthropic.com. You cannot use a free claude.ai account for either path.

The account type you have determines the auth path. This is not a preference. It is a technical requirement.

• claude.ai subscription path: You have a claude.ai account with a Pro or Max plan. Authentication uses OAuth and your browser. You do not manage API keys.
• Anthropic API path: You access Claude models through the API at console.anthropic.com and pay per token. You create API keys in the console and pass them directly to Claude Code.
• Free accounts cannot authenticate: The free claude.ai tier does not include Claude Code access. Authentication will fail immediately. Upgrade to Pro or Max, or use an API account.
• API key advantages: API key authentication gives more control over which model you use and enables headless and CI/CD usage without OAuth browser flows.
• OAuth simplicity: OAuth is simpler for individual developers on subscriptions. No key management, no environment variable setup, no expiry handling beyond a 90-day token refresh.

For a breakdown of what each plan includes and costs, the Claude Code plan comparison covers the differences between Free, Pro, and Max.

How Do You Authenticate with a Claude.ai Subscription (OAuth)?

Run claude in your terminal. The first launch triggers the OAuth flow automatically. Claude Code opens a browser window, you authorise access, and a session token is stored locally. You will not need to repeat this for 90 days.

The browser step is the only part that requires action beyond the terminal.

• Start the flow: Run claude in your terminal. Authentication starts automatically on the first launch.
• Browser opens automatically: On macOS and Windows, Claude Code attempts to open your default browser. On Linux and WSL, it may only display the URL in the terminal.
• Authorise in the browser: Log in to claude.ai if prompted, then click "Authorise" to grant Claude Code access to your account.
• Terminal confirms success: After authorising, Claude Code stores a session token at ~/.claude/. You do not need to re-run this flow unless the token expires.
• Subscription check: If the browser returns an error page, confirm your claude.ai plan is Pro or Max. A free account will show an authorisation error at this step.
• Terminal hang after browser auth: Press Enter once if the terminal does not resume automatically. Some terminal configurations do not detect the browser callback.

How Do You Authenticate with an API Key?

Retrieve your API key from console.anthropic.com and add it to your shell profile as ANTHROPIC_API_KEY. Setting it only in the terminal session means it disappears on every restart. Adding it to .bashrc or .zshrc makes it permanent.

The persistence step is what most documentation skips, and it is why most API key setups appear to break.

• Get your key from the console: Log in to console.anthropic.com, go to API Keys, and create a new key. Copy it immediately. It is only shown once.
• Method 1 (session only): Run export ANTHROPIC_API_KEY="sk-ant-..." in your terminal. This lasts only for that session.
• Method 2 (permanent, recommended): Add export ANTHROPIC_API_KEY="sk-ant-..." to your ~/.bashrc (Linux/WSL) or ~/.zshrc (macOS). Then run source ~/.bashrc to activate it.
• Method 3 (CI/CD runtime): Run ANTHROPIC_API_KEY="sk-ant-..." claude to pass the key at runtime. Use this when the key is injected as a CI environment variable.
• Verify the key is active: Run claude --version or start claude. If the key is valid, Claude Code launches without an auth prompt.
• Treat keys as secrets: Do not commit API keys to version control. Do not store them in .env files tracked by git.

How Do You Fix the Most Common Authentication Errors?

Most authentication errors fall into six categories: key not persisting, OAuth subscription mismatch, invalid key format, install integrity failure, expired token, and WSL browser issues. Each has a direct one-step fix.

These are the errors that stop most users at the last stage of setup.

• "Not authenticated" on every launch: The API key is not persisting. Confirm the export line is in .bashrc or .zshrc, not just entered once in the terminal, and that you ran source ~/.bashrc after adding it.
• OAuth returns "Access denied" or "Subscription required": Your claude.ai account does not have an active Pro or Max plan. The free tier cannot authenticate Claude Code. Upgrade at claude.ai/settings.
• "Invalid API key" error: The key was copied with extra spaces or line breaks, or it has been revoked. Generate a new key at console.anthropic.com.
• Auth completes but Claude Code does not start: Run claude --version to confirm the install is intact. If that fails, reinstall with npm install -g @anthropic-ai/claude-code.
• OAuth token expires mid-project: Run claude /logout followed by claude to re-run the OAuth flow. Your project files and CLAUDE.md are not affected.
• WSL/Linux "Cannot open browser" during OAuth: Copy the URL displayed in the terminal and open it in your Windows or Linux browser manually. Authentication will complete and the terminal will resume.

How Do You Manage Authentication for Multiple Projects or Environments?

Claude Code authentication is global, not per-project. One set of credentials covers all projects on the machine. For multiple accounts or CI/CD pipelines, use environment variable switching or injected secrets.

Authentication scoping is one of the more common points of confusion for developers using Claude Code across different contexts.

• Authentication is machine-wide: Once authenticated, all projects on that machine use the same credentials. There is no per-project login.
• Multiple API accounts: Use shell profiles or a tool like direnv to load different ANTHROPIC_API_KEY values per directory or project.
• CI/CD injection: Inject the API key as a CI secret environment variable such as ANTHROPIC_API_KEY in GitHub Actions secrets. Never hardcode it in workflow files.
• Reset authentication completely: Delete ~/.claude/ and run claude to re-authenticate from scratch. This covers both OAuth tokens and any cached credentials.
• Team environments: Each developer authenticates individually with their own credentials. There is no shared team authentication model for the CLI.

Conclusion

Claude Code authentication is straightforward once you know which of the two paths applies to your account type. OAuth is for claude.ai subscribers. API key is for API users.

The errors that stop most people are environment variable persistence and account tier mismatches. Both have direct fixes covered above.

After authentication completes and claude launches successfully, navigate to a project folder and give Claude Code a simple task. If it responds and modifies files correctly, the full stack is working.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

Need Help Getting a Claude Code Workflow Running Beyond Authentication?

Authentication is the entry point. The harder challenge is building reliable, production-grade workflows once Claude Code is running, especially across teams and CI/CD pipelines.

At LowCode Agency, we are a strategic product team, not a dev shop. We help teams move from individual developer setups to structured AI workflows integrated with real production systems.

• API key and secrets management: We configure secure credential handling for Claude Code across development, staging, and production environments.
• CI/CD pipeline integration: We set up Claude Code in your automated pipelines with proper authentication injection, not hardcoded keys in workflow files.
• Multi-environment setup: We build the shell profile and environment variable architecture for teams using Claude Code across different projects and accounts.
• Agentic workflow development: We design and build multi-step AI workflows where authenticated Claude Code instances orchestrate tasks across your stack.
• CLAUDE.md architecture: We structure your project memory files so Claude Code performs consistently from the first authenticated session, not just the first run.
• Team onboarding: We document and deploy the authentication and setup process so every developer on the team gets a working environment without ad-hoc debugging.
• Full product team: Strategy, design, development, and QA from a single team that treats your AI tooling as a product, not an IT ticket.

We have built 350+ products for clients including Coca-Cola, American Express, and Medtronic.

If you want Claude Code working reliably across your team and pipeline, get in touch.