Anthropic API Authentication, Environment Variables, and Safe Local Setup

The first time I accidentally committed an API key to a public GitHub repository, I learned the lesson the expensive way. It was not an Anthropic key—this was years earlier, during a different project—but the pattern was identical. I had hard-coded the secret “just for a quick test,” pushed the branch, and only noticed the exposure when a scanner bot emailed me thirty minutes later. The key was rotated, the repository was scrubbed, and I spent the rest of the afternoon writing a short personal rule that has stayed with me ever since:

Secrets never live in source files. Not even temporarily. Not even in a private repo. Not even “just this once.”

That rule is the entire reason this post exists. In the previous article we made a working Anthropic request by exporting ANTHROPIC_API_KEY in the terminal. That approach is fine for a single interactive session. It is not fine for anything that will live longer than a coffee break. Today we will build the smallest useful local setup that keeps the key out of your code, out of your shell history when possible, and out of your version control system. We will also look at the common ways this setup breaks and how to notice the failures early.

As always:

Build the smallest useful version, then test what breaks.

What You Will Have Working by the End

• A project that loads the Anthropic API key from a .env file

• A .gitignore that actually prevents the key from being committed

• A short verification script that fails loudly if the key is missing

• A clear mental model of where the key lives at each stage of the request

• Three realistic failure modes and the fastest way to diagnose each one

No production secret managers yet. No Docker. No CI. Just the local foundation every later tutorial on this site will assume you already have.

Why Environment Variables Are Not Enough by Themselves

Exporting a variable in the current shell works until you open a new terminal tab, switch machines, or hand the project to a teammate. At that point the key disappears and the next person (or your future self) has to rediscover the setup. The standard solution in the Python ecosystem is a .env file loaded by python-dotenv. The file stays on disk, never enters git, and is read at runtime.

I have seen teams skip this step because “we are just prototyping.” Prototypes have a habit of becoming the code that ships. Treat the local setup as production-grade from the first commit.

Step 1: Project Skeleton

Create a clean directory and virtual environment (same pattern as the previous post):

Bash

mkdir anthropic-auth-setup
cd anthropic-auth-setup
python3 -m venv .venv
source .venv/bin/activate
pip install anthropic python-dotenv

We now have two packages: the official Anthropic SDK and the small helper that loads .env files.

Step 2: Create the .env File and Protect It

Create a file named .env in the project root:

Bash

ANTHROPIC_API_KEY=sk-ant-api03-your-real-key-here

Immediately create a .gitignore file that contains at least these lines:

text

.env
.venv/
__pycache__/
*.pyc
.DS_Store

Commit the .gitignore before you do anything else. I still remember the mild panic of realizing I had staged a .env file and then having to dig through git reset and git rm --cached. Making the ignore rule the first commit removes that entire class of mistake.

If you already have a repository and the .env was ever committed, rotating the key is mandatory. Anthropic’s console lets you revoke a key in a few clicks. Do it the moment you suspect exposure.

Step 3: The Minimal Loading Pattern

Create auth_check.py:

Python

import os
from dotenv import load_dotenv
from anthropic import Anthropic

# Load variables from .env into the process environment
load_dotenv()

api_key = os.getenv("ANTHROPIC_API_KEY")

if not api_key:
    raise RuntimeError(
        "ANTHROPIC_API_KEY is missing. "
        "Create a .env file in the project root or export the variable."
    )

if not api_key.startswith("sk-ant-"):
    raise RuntimeError(
        "ANTHROPIC_API_KEY does not look like a valid Anthropic key. "
        "Check that you copied the full value."
    )

client = Anthropic(api_key=api_key)

# Smallest useful request so we know the key actually works
response = client.messages.create(
    model="claude-sonnet-5",  # verify current ID in official docs
    max_tokens=64,
    messages=[
        {
            "role": "user",
            "content": "Reply with exactly the words: auth setup works."
        }
    ]
)

print(response.content[0].text)
print(f"Model used: {response.model}")
print(f"Input tokens: {response.usage.input_tokens}")

Run it:

Bash

python auth_check.py

You should see the exact phrase “auth setup works.” followed by the model name and a tiny token count. That is the verification step. If the script raises a RuntimeError, the key is either missing or malformed. If the Anthropic client raises an authentication error, the key is present but invalid or revoked.

Notice that I still pass api_key=api_key explicitly to the client. The SDK will also read the environment variable on its own, but being explicit makes the data flow easier to follow when you later move the same code into a container or a serverless function.

Where the Key Lives at Each Stage

It helps to keep a mental map:

1. Disk — the .env file (never committed)

2. Process environment — after load_dotenv() runs

3. Client object — when you instantiate Anthropic(api_key=...)

4. Network request — the SDK places the key in the X-Api-Key header

At no point should the key appear in application logs, exception messages, or print statements. The verification script above deliberately does not print the key itself. If you ever feel the urge to print(api_key) for debugging, print only the first eight characters and the length instead.

Three Common Failure Modes and How to Spot Them

1. The Key Is Present but the Request Still Fails with 401

This usually means the key was rotated, revoked, or copied incompletely. Open the Anthropic Console, confirm the key is still active, and generate a fresh one if needed. Update the .env file and re-run the verification script. Do not keep old keys “just in case.”

2. The Script Works in Your Terminal but Fails for a Teammate

The teammate is missing the .env file. The correct response is not to email them the key. The correct response is to document the expected variable name and let them create their own key in the Console. Shared keys are a liability; individual keys with clear ownership are not.

3. The Key Appears in Shell History or Process Lists

If you ever typed export ANTHROPIC_API_KEY=sk-ant-... directly in the terminal, that line may live in your shell history file. On many systems you can clear the relevant entries, but the safer long-term habit is to load the key only through .env or a proper secrets manager. For local development the .env approach is sufficient.

I keep a private checklist I run whenever I start a new Anthropic project:

• .env exists and contains only the key

• .gitignore contains .env

• Verification script fails cleanly when the key is removed

• No print or log statement ever emits the full key

Running that checklist takes less than a minute and has saved me from several near-misses.

A Slightly More Defensive Pattern for Scripts

When a script will be run by other people (or by future you on a different machine), I like a slightly louder failure:

Python

import os
import sys
from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()

api_key = os.getenv("ANTHROPIC_API_KEY")
if not api_key:
    print("ERROR: ANTHROPIC_API_KEY not set.", file=sys.stderr)
    print("Create a .env file or export the variable.", file=sys.stderr)
    sys.exit(1)

client = Anthropic(api_key=api_key)
# ... rest of the script

Exiting with a non-zero status makes the failure visible to any automation that might call the script later. It also keeps the error message out of the normal stdout stream that your application logic might be parsing.

What This Setup Does Not Cover Yet

This local pattern is intentionally limited. It does not:

• Pull secrets from AWS Secrets Manager, HashiCorp Vault, or similar

• Rotate keys automatically

• Scope keys to specific IP ranges or project permissions

• Protect keys inside Docker images or CI runners

• Audit who used which key and when

Those topics belong to the Deployment category and will appear in later posts. For local development and early prototyping, the .env + .gitignore + verification script combination is the smallest useful version that actually stays safe.

Verification Checklist You Can Run Right Now

1. Confirm .env exists and is listed in .gitignore.

2. Run python auth_check.py and confirm the expected phrase appears.

3. Temporarily rename .env to .env.bak and confirm the script raises a clear error.

4. Restore the file and confirm the script works again.

5. Run git status and confirm .env is not listed as an untracked or staged file.

If all five steps pass, your local authentication baseline is solid.

Update Note

The Anthropic Python SDK continues to read ANTHROPIC_API_KEY by default. The python-dotenv package remains the lightest way to load a local file. Model identifiers change; always verify the current recommended ID in the official documentation before copying examples into longer-lived code. Authentication headers and error shapes have been stable for a long time, but it is still worth skimming the latest SDK changelog when you upgrade the package.

Looking Ahead

The next post moves from authentication into the shape of the requests themselves: messages, system instructions, and how context windows actually behave when you start sending real conversation history. Once those pieces are clear we can begin building the first tool-using agent without the foundation wobbling underneath us.

For now, keep the verification script. When something larger fails later, you will be glad you can still prove in under a second that the key is present and valid.

Build the smallest useful version, then test what breaks.

— Caleb Fletcher

Boise, Idaho