Claude Media
ANTHROPIC_AUTH_TOKENとANTHROPIC_API_KEYの違い
Claude CodeTips

ANTHROPIC_AUTH_TOKENとANTHROPIC_API_KEYの違い

Claude CodeのANTHROPIC_AUTH_TOKENとANTHROPIC_API_KEYは送るヘッダーが違います。使い分けの基準、優先順位、適用されない面までをまとめます。

読了目安 約9分

ANTHROPIC_AUTH_TOKENとANTHROPIC_API_KEYは、どちらもClaude Codeの認証をシェルの環境変数で渡す仕組みですが、送るヘッダーの形式が違います。混同すると、ゲートウェイ側はAuthorization: Bearerを待っているのにX-Api-Keyを送ってしまう、といった食い違いが起きます。ヘッダーの違いと使い分けの基準、両方設定したときの優先順位、そして適用されない面までをまとめます。

送るヘッダーの違い

ANTHROPIC_AUTH_TOKENは値をBearer という接頭辞付きでAuthorizationヘッダーに入れます。LLMゲートウェイやプロキシがBearerトークン方式で認証する構成向けの変数です。

ANTHROPIC_API_KEYは値をそのままX-Api-Keyヘッダーに入れます。Claude Consoleで発行したAPIキーで、Anthropicの直接APIに接続する構成向けです。

名前が似ていて機能も「認証情報を環境変数で渡す」という点で共通しているため、どちらか一方だけを覚えて使い回すと、ヘッダー形式の違いでゲートウェイ側の認証に失敗します。値そのものが正しくても、ヘッダーの形式が合っていなければ通りません。

使い分けの基準

接続先使う変数送られるヘッダー
Bearerトークンで認証するLLMゲートウェイ・プロキシ使う変数ANTHROPIC_AUTH_TOKEN送られるヘッダーAuthorization: Bearer <値>
Anthropicの直接API(Claude Consoleのキー)使う変数ANTHROPIC_API_KEY送られるヘッダーX-Api-Key: <値>
動的・短命な認証情報(vaultから取得するトークン等)使う変数apiKeyHelper(設定ファイル)送られるヘッダー生成した値をどちらのヘッダーにも設定可能

判断の起点は「相手が待っているヘッダー形式」です。ゲートウェイの認証ドキュメントにAuthorization: BearerとあればANTHROPIC_AUTH_TOKEN、x-api-keyとあればANTHROPIC_API_KEYを選びます。接続先をapi.anthropic.com以外に切り替える設定そのものは、この2つの変数ではなくANTHROPIC_BASE_URLが担います。認証方式と接続先は別のレイヤーなので、ゲートウェイ運用ではこの2種類の変数を組み合わせて使うのが基本形です。

設定のしかた

シェルの環境変数として渡します。

export ANTHROPIC_AUTH_TOKEN="your-bearer-token"
claude

設定ファイルのenvキーに書く場合は、ANTHROPIC_API_KEYも含めて次のようになります。どちらか一方だけを書きます。

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-bearer-token"
  }
}

値が実際に届いているかは、同じシェルでecho $ANTHROPIC_AUTH_TOKENのように出力して確認します。設定ファイルのenvブロックに書いた場合は保存直後に反映されますが、シェルのexportは新しいセッションでclaudeを起動しないと反映されません。

apiKeyHelperで動的な認証情報を渡す

短命なトークンをvaultなどから取得して定期的に更新したい場合は、環境変数の値を都度書き換える代わりに、設定ファイルでapiKeyHelperにスクリプトを指定する方法があります。スクリプトの出力した値は、X-Api-KeyとAuthorization: Bearerの両方のヘッダーに設定されます。

apiKeyHelperは既定で5分ごと、またはHTTP 401応答を受けたタイミングで再実行されます。再実行の間隔はCLAUDE_CODE_API_KEY_HELPER_TTL_MSで変更できます。スクリプトが10秒以上かかると、プロンプトバーに経過時間つきの警告が出ます。頻繁に出るようなら、スクリプト側の処理を見直す合図です。スクリプトがエラー終了する・タイムアウトする・何も出力しないといった失敗が3回続くと、「Your apiKeyHelper script is failing」でリクエストが失敗します。

ANTHROPIC_AUTH_TOKEN・ANTHROPIC_API_KEYが値を固定で渡すのに対し、apiKeyHelperは毎回スクリプトを実行して値を取得し直せる点が違います。固定値で足りるなら環境変数、ローテーションが必要ならこちらを選びます。

優先順位 — 両方設定したときとサブスクリプションとの関係

複数の認証情報が存在するとき、Claude Codeは次の順で選びます(上が優先)。

  1. CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEX / CLAUDE_CODE_USE_FOUNDRYによるクラウドプロバイダー認証
  2. ANTHROPIC_AUTH_TOKEN
  3. ANTHROPIC_API_KEY
  4. apiKeyHelperスクリプトの出力
  5. CLAUDE_CODE_OAUTH_TOKEN(claude setup-tokenで発行する長期トークン。CI環境やブラウザ操作ができないサーバーでの使い方はClaude Code SSH接続ガイドにまとめています)
  6. Anthropicプロファイル・フェデレーション認証情報
  7. /loginによるサブスクリプションのOAuth認証情報

この優先順位の外側にもう1つ経路があります。組織がクラウドゲートウェイ経由のサインインを使っている場合、そのセッションはCLAUDE_CODE_USE_BEDROCKのようなプロバイダー選択と同格の扱いで、上記の並びより優先されます。ゲートウェイセッションが存在するときは、ANTHROPIC_AUTH_TOKENやANTHROPIC_API_KEYを設定していてもゲートウェイのトークンで認証され、これらの環境変数は使われません。

Claude Pro・Max・Team・EnterpriseのサブスクリプションでログインしていてもANTHROPIC_API_KEYを環境に残していると、承認後はそちらが優先されます。組織が無効化・期限切れになっているAPIキーの場合、これが認証エラーの原因になります。unset ANTHROPIC_API_KEYでサブスクリプションに戻し、/statusで有効な認証方式を確認します。対話モードでは初回だけAPIキー使用の承認を求められ、以降は選択が記憶されます。非対話モード(-pフラグ)では、値が設定されていれば常にAPIキーが優先して使われます。

組織側でforceLoginOrgUUIDのような組織制限を設定している場合、ANTHROPIC_AUTH_TOKEN・ANTHROPIC_API_KEY・apiKeyHelperのいずれかによる認証情報はすべて起動時にブロックされます。環境変数の認証情報は、どの組織に属するかを検証できないためです。組織側でAPIキー認証自体を無効化しているケースはClaude Codeで組織がAPIキー認証を無効化したときの対処で扱っています。

適用されない面 — Desktop・Claude Code on the Web

apiKeyHelper・ANTHROPIC_API_KEY・ANTHROPIC_AUTH_TOKENが効くのは、CLI本体とそれをラップする面だけです。VS Code拡張、Agent SDK、GitHub Actionsはここに含まれます。

Claude Desktopとクラウド上のセッションはこの3つを読みません。OAuthでの認証が前提だからです。例外はDesktopでサードパーティの推論設定を使っているセッションで、その場合は設定側の認証情報が使われます。Claude Code on the Webも常にサブスクリプションの認証情報を使い、サンドボックス環境でANTHROPIC_API_KEYやANTHROPIC_AUTH_TOKENを設定してもサブスクリプションを上書きしません。

面ごとに効き方が違う変数を、CLIで確認した設定のままDesktopやWebに持ち込んでも反映されない、という取り違えが起きやすいポイントです。

/loginによるサブスクリプション認証は、macOSなら暗号化されたKeychain、Linuxならファイルモード0600の~/.claude/.credentials.json、Windowsならユーザープロファイルのアクセス制御下に保存されます。ANTHROPIC_AUTH_TOKENやANTHROPIC_API_KEYはこの管理の外にあるプレーンな環境変数です。シェルの履歴やプロセス一覧、CI設定のログに値がそのまま残る経路があるため、値の取り扱いはログインベースの認証情報より一段注意が要ります。

値が壊れているときのエラーメッセージも別々

値そのものにHTTPヘッダーへ入れられない文字(改行や制御文字など)が混ざっていると、Claude Codeはリクエストを送る前に検知して止めます。このときのエラーメッセージは、どちらの変数が原因かで文言が変わります。

Invalid auth token · Fix external auth token · Invalid Authorization header value from ANTHROPIC_AUTH_TOKEN: it contains a line break at character 41 (120 characters on 2 lines).

ANTHROPIC_API_KEY側で同じ問題が起きると「Invalid API key · Fix external API key」という文言になり、続く説明でX-Api-Keyヘッダーの何文字目に問題があるかを示します。位置と文字数は示されますが、値そのものは表示されません。値をコピーしたときに改行や不可視文字(ゼロ幅スペース、装飾的な引用符など)が紛れ込んでいないかを疑う手がかりになります。

APIが実際にキーを拒否した場合(タイポや失効)はANTHROPIC_API_KEY側で「Invalid API key」、apiKeyHelperの出力が壊れている場合は「Your apiKeyHelper script is failing」と、原因ごとにメッセージが分かれます。エラー文言の頭に出る変数名を見れば、3つの経路のどれが原因かを切り分けられます。

2つの変数が別々に存在する理由

認証方式を1つの変数にまとめず、ヘッダー形式ごとに変数を分けているのは、Bearerトークン方式のゲートウェイとAnthropicの直接APIキー方式が、そもそも別の認証プロトコルだからです。どちらか一方に寄せて共用させると、ゲートウェイ移行のたびにヘッダー形式の変換層を挟む必要が出てきます。優先順位でANTHROPIC_AUTH_TOKENをANTHROPIC_API_KEYより上に置いているのも、ゲートウェイ経由の構成をより新しい標準とみなしている並びです。今後ゲートウェイ経由の運用が主流になるほど、この優先順位の意味は増します。

よくある質問

両方とも設定していないとどうなりますか

apiKeyHelperも未設定なら、CLAUDE_CODE_OAUTH_TOKENかサブスクリプションのOAuth認証情報が使われます。個人利用でログイン済みなら、通常はこの状態のままで問題ありません。

apiKeyHelperとANTHROPIC_API_KEYはどちらが優先されますか

ANTHROPIC_API_KEYが優先されます。優先順位の並びではapiKeyHelperより上です。両方を設定している場合、apiKeyHelperの出力は使われません。

GitHub Actionsではどちらを使うべきですか

Bearerトークン方式のゲートウェイ経由ならANTHROPIC_AUTH_TOKEN、Claude Consoleで発行したAPIキーをそのまま使うならANTHROPIC_API_KEYです。どちらもSecretsに登録してenv経由で渡す使い方はワークフロー・面ともに対応しています。

値を変えたのにClaude Codeが古い認証情報を使い続けます

シェルのexportは新しいシェルセッションでclaudeを起動しないと反映されません。設定ファイルのenvブロックに書いた場合は保存直後に反映されますが、apiKeyHelperは既定で5分ごとか401応答時にしか再実行されない点に注意します。

今どちらの認証方式が使われているか確認する方法はありますか

/statusを実行します。Login methodの行にサブスクリプションアカウントが表示され、環境変数由来のキーを使っている場合はAPI keyの行が追加で表示されます。CLAUDE_CODE_OAUTH_TOKENを使っている場合はAuth tokenの行に変数名が表示されます。設定した変数のつもりが実は別の経路が優先されている、という状況を切り分けるときにまず見る場所です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →