Authenticating Claude API Calls with the x-api-key Header

Every request to the Claude API has to prove who is calling before the server will do anything else.

That proof is a single header: x-api-key, carrying your API key.

This page covers where to get a key, how to configure it for the Python SDK, and how to send it manually when you're not using the SDK.

Summary

The x-api-key header is how the Claude API authenticates every request, checked before the request body is even inspected.

The official Python SDK reads your key from the ANTHROPIC_API_KEY environment variable by default, so most code never touches the header directly.

You can also pass the key explicitly to the client constructor, which is useful for multi-key setups or per-request key rotation.

Raw HTTP callers (curl, requests, or another language's HTTP client) must set x-api-key themselves, along with a couple of other required headers.

Treating API keys like any other secret, never hardcoded, never committed, rotated on a schedule, is the difference between a minor scare and a real incident.

Recipe

Quick-reference recipe card - copy-paste ready.

import os
import anthropic
 
# Option 1: implicit - SDK reads ANTHROPIC_API_KEY from the environment
client = anthropic.Anthropic()
 
# Option 2: explicit - pass the key directly
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

When to reach for this:

• Setting up a new project: use the environment variable approach (Option 1).
• Supporting multiple accounts or key rotation in one process: use the explicit api_key argument (Option 2).
• Calling the API without the SDK: set the x-api-key header manually (see Working Example).
• Running in CI or a container: inject ANTHROPIC_API_KEY via your platform's secrets mechanism, not a checked-in file.

Working Example

import os
import anthropic
 
def get_client() -> anthropic.Anthropic:
    api_key = os.environ.get("ANTHROPIC_API_KEY")
    if not api_key:
        raise RuntimeError(
            "ANTHROPIC_API_KEY is not set. Export it before running this script."
        )
    return anthropic.Anthropic(api_key=api_key)
 
 
def main() -> None:
    client = get_client()
    response = client.messages.create(
        model="claude-sonnet-5-20260630",
        max_tokens=100,
        messages=[{"role": "user", "content": "Confirm that authentication is working."}],
    )
    print(response.content[0].text)
 
 
if __name__ == "__main__":
    main()

What this demonstrates:

• Failing fast with a clear error message when the key is missing, rather than letting a cryptic 401 surface later.
• Reading the key from the environment explicitly, which makes the dependency visible at the top of the script.
• Passing api_key explicitly to the constructor, which works identically to letting the SDK read the environment variable itself.

Deep Dive

How It Works

• The SDK's anthropic.Anthropic() constructor checks for an explicit api_key argument first; if none is given, it falls back to reading ANTHROPIC_API_KEY from the process environment.
• Internally, the SDK attaches your key as the x-api-key header on every outgoing HTTPS request, you never have to set it per call.
• The server validates this header before parsing the rest of the request body, which is why authentication failures return quickly and independently of whether your prompt or parameters are valid.
• A missing or invalid key raises anthropic.AuthenticationError in Python, mapped from a 401 HTTP response.

Raw HTTP Without the SDK

If you're calling the API directly (for a language without an SDK, or to debug at the HTTP level), set the header yourself:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-01-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-20260630",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Note that raw calls need both x-api-key and an anthropic-version header; the SDK sets the version header for you automatically.

Key Storage Options

Python Notes

# Prefer os.environ[...] (raises KeyError loudly) over os.environ.get(...)
# with a silent None fallback, when the key is genuinely required:
import os
 
api_key = os.environ["ANTHROPIC_API_KEY"]  # raises clearly if missing

Gotchas

• Hardcoding the key in source. It ends up in version control history permanently, even if you delete it in a later commit. Fix: use environment variables or a secrets manager, and add .env to .gitignore before the first commit that touches it.
• Committing a .env file by accident. A missing or misconfigured .gitignore entry silently leaks the key. Fix: add .env to .gitignore first, then verify with git status that it's untracked before your first commit.
• Confusing 401 (bad key) with 403 (valid key, no permission). Both are auth-stage errors but need different fixes. Fix: check the exception's status code; 401 means regenerate or fix the key, 403 means check the key's permissions/scope on your account.
• Logging the full request object, including headers, in debug output. This can leak the key into log files or observability tools. Fix: scrub or omit the x-api-key header when logging requests.
• Sharing one key across every environment (dev, staging, prod). A leak or bug in one environment compromises all of them. Fix: issue separate keys per environment so you can revoke one without affecting the others.
• Forgetting the anthropic-version header on raw HTTP calls. Raw callers sometimes copy the auth header but forget this one, causing confusing failures unrelated to authentication itself. Fix: always send both headers together for non-SDK calls.

Alternatives

FAQs

Related

• Understanding the Claude API Request Lifecycle - where authentication fits in the overall request flow.
• Installing and Configuring the Anthropic Python SDK - client setup beyond just the key.
• Claude API Error Codes and Troubleshooting Reference - full list of auth-related error codes.
• Building a Reusable Claude API Client Wrapper - centralizing key handling across an app.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the official anthropic Python SDK (latest 0.x release). Model names, SDK versions, and pricing move quickly - verify current specifics at platform.claude.com/docs before relying on them.