Claude Code Authentication Setup

Claude Code supports two authentication methods: an Anthropic API key for pay-per-token billing, or a Claude Max subscription for flat-rate access. The right choice depends on whether you are an individual developer, part of a team, or running Claude Code in automated pipelines.

This guide covers setup for both methods, team configuration patterns, and the security practices that prevent the most common authentication mistakes. Once authentication is configured, the Claude Code course is a practical next step for learning how to use Claude Code effectively across real development work.

If you have not yet installed Claude Code, start with the installation guide first.

The Two Authentication Methods

The fundamental difference is billing model. API key access charges per token processed. Claude Max charges a flat monthly rate regardless of usage volume. For developers who run many Claude Code sessions daily, Claude Max often costs less than equivalent API usage. For teams with unpredictable or low usage, API key billing avoids a fixed monthly commitment per seat.

Method 1: Anthropic API Key

Get Your API Key

Go to console.anthropic.com and sign in. Navigate to the API Keys section.

Create a new key and copy it immediately. Anthropic does not display the key again after initial creation.

If you lose it, you will need to create a new one.

Set the Environment Variable

The API key must be available as an environment variable named ANTHROPIC_API_KEY in any shell session where you run claude.

On Mac and Linux, add it to your shell configuration file:

# For zsh (default on Mac)
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.zshrc
source ~/.zshrc

# For bash (default on most Linux)
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.bashrc
source ~/.bashrc

Verify the variable is set:

echo $ANTHROPIC_API_KEY

This should print your key. If it prints nothing, the variable is not exported correctly.

Verify Authentication

Start Claude Code in any directory:

claude

If the key is valid and the network is reachable, Claude Code will start an interactive session. An authentication error at this stage usually means the key was not exported correctly or the session needs to be reloaded with source ~/.zshrc.

Method 2: Claude Max Subscription

Claude Max is Anthropic’s subscription plan for individuals and teams who want flat-rate access to Claude. The setup flow is simpler than API key configuration and does not require managing environment variables.

Authenticate via Browser

Run:

claude auth login

This opens a browser window pointing to Anthropic’s authentication service. Log in to your Anthropic account.

If your account has a Claude Max subscription active, the authentication completes and Claude Code stores a token locally at ~/.claude/. All subsequent claude commands in any directory will use this token automatically.

Verify Authentication

claude auth status

This shows the currently authenticated account and the authentication method in use. If you see your email address and Authenticated, the setup is complete.

Claude Max authentication stores a token on your local machine. This means you authenticate once per machine, not once per session. You do not need to set any environment variables.

When to Use Each Method

Use API key authentication when:

• CI/CD pipelines. Setting up GitHub Actions, GitLab CI, or Jenkins with Claude Code.
• Shared team access. Your team uses a central key managed by a secrets manager.
• Usage tracking. You want to attribute API costs at the project or team level.
• Multiple accounts. You need to switch between Anthropic accounts or environments.

Use Claude Max when:

• Heavy individual use. You run Claude Code frequently throughout the day.
• Simpler setup. No environment variable management required.
• Flat-rate billing. Easier to budget for than per-token usage-based billing.
• Existing subscriber. You already have a Claude Max subscription for Claude.ai.

Team Setup

Teams have two main configuration patterns: shared API keys or individual Claude Max subscriptions.

Shared API Key (Recommended for CI/CD)

For automated pipelines, store the API key in your CI/CD secrets manager and inject it as an environment variable at runtime. In GitHub Actions:

env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

For local developer setup with a shared key, distribute the key through a secrets manager (1Password, HashiCorp Vault, AWS Secrets Manager) rather than sharing it over Slack or email. Each developer sets the key in their local ~/.zshrc or ~/.bashrc.

Individual Claude Max Subscriptions

For teams where each developer runs Claude Code independently, individual Claude Max subscriptions are simpler to manage. Each developer runs claude auth login on their own machine with their own Anthropic account.

There are no shared secrets to rotate or distribute.

Security Best Practices

API keys are secrets. Mishandling them exposes your Anthropic account to unauthorized usage and unexpected costs.

Never commit API keys to git. This is the most common mistake.

Add .env to your .gitignore file before creating any .env files. If you accidentally commit a key, rotate it immediately at console.anthropic.com and consider the old key compromised.

Use .env files for local development projects. Create a .env file in your project root:

ANTHROPIC_API_KEY=sk-ant-your-key-here

Add .env to .gitignore:

echo '.env' >> .gitignore

Rotate keys periodically. Create a new key in the Anthropic console, update all places where the old key is set, then delete the old key. Quarterly rotation is a reasonable cadence for most teams.

Use separate keys for different environments. Create one key for local development, a separate key for staging, and a separate key for production CI/CD. This limits the blast radius if a key is compromised.

Never hardcode keys in source files. Always read keys from environment variables. Hardcoded keys in source files are discovered immediately by automated secret-scanning tools.

Switching Between Authentication Methods

You can switch between API key and Claude Max authentication at any time.

Switch from API key to Claude Max:

1. Run claude auth login and complete the browser OAuth flow
2. Claude Max authentication takes precedence when active
3. You can remove the ANTHROPIC_API_KEY line from your .zshrc if you no longer need API key access

Switch from Claude Max to API key:

1. Run claude auth logout to clear the stored token
2. Set ANTHROPIC_API_KEY in your shell configuration
3. Reload your shell with source ~/.zshrc

Check current authentication status:

claude auth status

This command shows which authentication method is currently active and which account is authenticated.

FAQ

Can I use both an API key and Claude Max at the same time?

Claude Code uses one authentication method per session. If both are configured, Claude Max (browser auth token) takes precedence over the ANTHROPIC_API_KEY environment variable. To use the API key instead, run claude auth logout to clear the Claude Max token.

What happens if my API key expires or is revoked?

Claude Code will return an authentication error at the start of the next session. Create a new key at console.anthropic.com, update your ~/.zshrc, and run source ~/.zshrc. No other configuration needs to change.

Is it safe to set my API key in ~/.zshrc?

It is the standard approach for local development. Your home directory is not accessible to other users on a single-user machine.

For shared machines or servers, use a secrets manager or environment injection at the process level rather than storing the key in a shell configuration file.

How do I share authentication for a team without exposing the API key?

Use a secrets manager. Popular options are 1Password Teams, HashiCorp Vault, AWS Secrets Manager, and GitHub Encrypted Secrets (for CI/CD). Each developer pulls the key from the secrets manager and sets it in their local environment. The key is never transmitted in plaintext over Slack, email, or chat.

Phos AI Labs is a CCA-F certified Claude implementation partner with 400+ engagements. If your team is configuring Claude Code across multiple developers or integrating it into CI/CD pipelines, contact us to discuss authentication patterns, cost management, and security configuration that fits your environment.