Wróć do przewodników
Troubleshooting·30 sierpnia 2026·Zaktualizowano 22 października 2026·6 min czytania

ANTHROPIC_AUTH_TOKEN vs ANTHROPIC_API_KEY — which one Claude Code actually reads

These are not aliases. One becomes `x-api-key`, the other becomes `Authorization: Bearer` — and when both are set, the one you did not mean to use can win. Most "my key is correct but auth fails" reports against a custom base URL are this.

Last reviewed on .

These are not aliases. One becomes `x-api-key`, the other becomes `Authorization: Bearer` — and when both are set, the one you did not mean to use can win. Most "my key is correct but auth fails" reports against a custom base URL are this.

The error

the two variables
# Sent as:  x-api-key: <value>
export ANTHROPIC_API_KEY="sk-ant-..."

# Sent as:  Authorization: Bearer <value>
export ANTHROPIC_AUTH_TOKEN="sk-kn-..."

# Where those headers go:
export ANTHROPIC_BASE_URL="https://api.kunavo.com"

Causes and fixes at a glance

CauseFix
Gateway expects a bearer token; you set the API key variableMost OpenAI-compatible gateways authenticate on `Authorization: Bearer`. Put the gateway key in ANTHROPIC_AUTH_TOKEN.
Both variables set, from different providersA stale ANTHROPIC_API_KEY in your shell profile can be sent alongside the token. Unset the one you are not using.
Base URL set, credentials not changedPointing at a new host does not make an old provider's key valid there. The credential has to change with the host.
Variable set in a different shell than the one running the toolAn export in an interactive shell does not reach a GUI-launched process. Verify inside the same environment.

See what your environment is actually holding

Check both, in the shell that launches the tool, before changing anything. A surprising share of these sessions have both set — often one from a months-old profile edit nobody remembers.

inspect-env.sh
for v in ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL; do
  printf '%-22s %s\n' "$v" "$(printenv "$v" | cut -c1-12)"
done

# Prefixes tell you the provider at a glance:
#   sk-ant-  Anthropic direct
#   sk-kn-   Kunavo

Set the pair that matches your host, and unset the other

Treat host and credential as one unit. Against a third-party base URL, that is normally the bearer token plus the base URL, with the direct API key explicitly unset so it cannot be picked up.

third-party.sh
unset ANTHROPIC_API_KEY

export ANTHROPIC_AUTH_TOKEN="sk-kn-..."
export ANTHROPIC_BASE_URL="https://api.kunavo.com"

# On Kunavo, pin served models too: Claude Code's default and its opus and
# sonnet aliases follow Anthropic's newest models, and the sonnet alias asks
# for Sonnet 5.5, which Kunavo does not serve — unpinned, that request 404s.
export ANTHROPIC_MODEL="claude-sonnet-5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-5-5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"

claude

Confirm on the wire, not in your head

If auth still fails, take the environment out of the question: issue the request by hand with the header you believe is being sent. A 200 here with a failure in the tool means the tool is not reading the variable you set — most often a different shell, or a config file overriding it.

verify.sh
curl -s -o /dev/null -w '%{http_code}\n' \
  "$ANTHROPIC_BASE_URL/v1/models" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

Anthropic SDKs since October 21, 2026: the API key goes in Authorization: Bearer

Since API version 2026-10-21, Anthropic's SDKs send the API key as Authorization: Bearer instead of x-api-key: the Python SDK from 2.0.0, the TypeScript SDK from 1.0.0 and the other new major versions, whether the key comes from the api_key argument or from ANTHROPIC_API_KEY. A proxy or gateway that reads only x-api-key now finds no key and answers 401. Anthropic's migration guide tells you to change any proxy or gateway that reads or sets X-Api-Key, and notes that the Claude API itself accepts a key in either header (https://platform.claude.com/docs/en/api/migration-2026-10-21, read October 22, 2026). Kunavo accepts both: in our test on October 22, 2026, the Python SDK 2.0.0 and 2.1.0 and the TypeScript SDK 1.0.0 and 1.1.0 sent the key as a bearer token, older versions sent x-api-key, and Kunavo accepted every request. The new SDKs also hold one credential per client: with no key passed in code and both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN set, they use the API key. When a request carries both headers, Kunavo uses the Authorization one and ignores x-api-key, so do not put another service's token in Authorization and your Kunavo key in x-api-key. Claude Code reads its variables as described above.

sdk2_kunavo.py
import anthropic

# Python SDK 2.x sends this key as "Authorization: Bearer sk-kn-...";
# Kunavo accepts it there, and as x-api-key from older versions.
client = anthropic.Anthropic(base_url="https://api.kunavo.com", api_key="sk-kn-...")

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=32,
    messages=[{"role": "user", "content": "ping"}],
)
print(msg.content[0].text)

If you’re calling through Kunavo

Kunavo reads the key from either `Authorization: Bearer` or `x-api-key`, so the header is not what decides it. With Claude Code the working pair is still ANTHROPIC_AUTH_TOKEN plus ANTHROPIC_BASE_URL — the token takes effect without the one-time approval ANTHROPIC_API_KEY needs — and ANTHROPIC_API_KEY should be unset rather than left over, because a stale value there is the single most common cause of a session that looks configured and still refuses. The same `sk-kn-` key works unchanged as an OpenAI-style bearer token against /v1/chat/completions, so one credential covers both shapes. The full setup, including the model names to use, is in our Claude Code 401 guide.

Frequently asked questions

If both are set, which wins?

Do not rely on the answer — it is a precedence rule that has changed between versions and differs across SDKs. Set exactly one and unset the other; that is the only configuration that behaves the same everywhere.

Can I use ANTHROPIC_AUTH_TOKEN with Anthropic directly?

For Claude Code, a direct Anthropic key belongs in ANTHROPIC_API_KEY, and the token variable exists for hosts that expect a bearer credential. The Claude API itself accepts an API key in either header, which is why Anthropic's SDKs could move the key to Authorization: Bearer on October 21, 2026.

Does the SDK use the same variables?

The Python and TypeScript SDKs read ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN. From Python 2.0.0 and TypeScript 1.0.0 they send the API key as Authorization: Bearer; earlier versions send it as x-api-key. If you point an SDK at a gateway, pass the credential explicitly rather than relying on the environment.

Related guides

More error semantics live in the error reference; getting a key takes a minute via signing up and the authentication guide.