Claude Media
ANTHROPIC_AUTH_TOKENとANTHROPIC_API_KEYの違い
Claude CodeTips

ANTHROPIC_AUTH_TOKENとANTHROPIC_API_KEYの違い

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

読了目安 約15分

ANTHROPIC_AUTH_TOKENとANTHROPIC_API_KEYは、どちらもClaude Codeの認証をシェルの環境変数で渡す仕組みですが、送るヘッダーの形式が違います。混同すると、ゲートウェイはAuthorization: Bearerを待っているのにX-Api-Keyを送ってしまう、といった食い違いで401になります。使い分けの基準と優先順位のほか、手元のv2.1.285でclaude auth statusの表示を確かめた結果、ゲートウェイ運用で起きることまでをまとめます。

送るヘッダーの違い

くらべる

2つの変数の送り方

Bearer方式

ANTHROPIC_AUTH_TOKEN

設定した値の前にBearer が付いてAuthorizationヘッダーに入ります。値にはトークン本体だけを書きます。LLMゲートウェイやプロキシがBearerトークンで認証する構成向けです。

キー方式

ANTHROPIC_API_KEY

値がそのままX-Api-Keyヘッダーに入ります。Claude Consoleで発行したAPIキーで、Anthropicの直接APIにつなぐ構成向けです。

値そのものが正しくても、ヘッダーの形式が相手と合っていなければ通りません。公式のゲートウェイ接続ガイドも、変数を取り違えると資格情報が相手の読まないヘッダーに乗って401になると書いています。確認リクエストが401だったら、もう一方の変数に替えて試す流れです。

使い分けの基準

接続先使う変数送られるヘッダー
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が担います。認証方式と接続先は別のレイヤーなので、ゲートウェイ運用では両方を組み合わせるのが基本形です。

設定のしかた

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

export ANTHROPIC_AUTH_TOKEN="your-bearer-token"
claude

設定ファイルのenvキーに書く方法もあります。ANTHROPIC_API_KEYを書く場合も形は同じで、どちらか一方だけを書きます。

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

反映のタイミングは書き場所で変わります。シェルのexportはClaude Codeが起動時に読むため、次にclaudeを起動したときからです。ユーザー設定のenvは、保存した変更が実行中のセッションにも反映されます。プロジェクト設定・ローカル設定のenvは、ワークスペースを信頼した後に適用されます。

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

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

スクリプトの再実行は、既定の5分ごと、HTTP 401・403を受けたとき、そしてv2.1.246以降は期限切れのJWTを送る前です。後の2つは、出力が送信する認証情報そのものでANTHROPIC_AUTH_TOKENが未設定のときだけ働きます。間隔はCLAUDE_CODE_API_KEY_HELPER_TTL_MSで変えられます。

出力の作法にも決まりがあります。標準出力にはキーだけを出し、終了コードは0にします。v2.1.227以降は、キーと一緒にバナーやログ行を出すとヘルパーの失敗になります。10秒以上かかるとプロンプトバーに経過時間つきの警告が出るので、頻繁に見るならスクリプト側の見直しどきです。

失敗は「Your apiKeyHelper script is failing」として表に出ます。エラー終了・タイムアウト・出力なしのどれでも同じで、Claude Codeは最大2回再実行して合計3回の試行のうちに失敗を報告します。v2.1.274以降は、/statusのapiKeyHelperの行にFailingと直近の失敗内容が出ます。ここで/loginを実行しても直りません。設定が残るかぎり、ヘルパーの出力が保存済みのログインより優先されるためです。

固定値で足りるなら環境変数、ローテーションが必要ならこちらです。

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

複数の認証情報があるとき、Claude Codeは次の順で選びます。

優先順位

認証情報を選ぶ順番

  1. 1

    クラウドプロバイダー認証

    CLAUDE_CODE_USE_BEDROCK・CLAUDE_CODE_USE_VERTEX・CLAUDE_CODE_USE_FOUNDRYのいずれかを設定したとき。

  2. 2

    ANTHROPIC_AUTH_TOKEN

    Bearerトークン。ゲートウェイ向けの変数が、APIキーより上に来ます。

  3. 3

    ANTHROPIC_API_KEY

    Consoleのキー。

  4. 4

    apiKeyHelperの出力

    スクリプトが返した値。

  5. 5

    CLAUDE_CODE_OAUTH_TOKEN

    claude setup-tokenで発行する長期トークン。CIやブラウザ操作ができないサーバーでの使い方はClaude Code SSH接続ガイドにまとめています。

  6. 6

    Anthropicプロファイル・フェデレーション認証情報

    antCLIやWorkload Identity Federationの資格情報。ant auth loginが書いたプロファイルは、ANTHROPIC_PROFILEで名指ししたときだけここに入ります。

  7. 7

    /loginのサブスクリプション認証

    Pro・Max・Team・Enterpriseの既定です。

apiKeyHelperとANTHROPIC_API_KEYを両方設定した場合も、上位のANTHROPIC_API_KEYが使われ、ヘルパーの出力は使われません。

この順位の外側にもう1つ経路があります。組織がClaude appsゲートウェイ経由のサインインを使っていると、そのセッションはクラウドプロバイダーの選択と同じ種類の扱いで、それも含めて上の並びより優先されます。ゲートウェイセッションがあるあいだは、ANTHROPIC_AUTH_TOKENやANTHROPIC_API_KEYを設定していてもゲートウェイのトークンで認証されます。

管理設定でforceLoginMethodを"gateway"にするかforceLoginGatewayUrlを設定した場合は、さらに強く縛られます。クラウドプロバイダーを選ぶ変数がないかぎり、他の認証情報は読まれず、/loginでのゲートウェイサインインを求められます。v2.1.261以降(forceLoginGatewayUrlだけを設定した端末はv2.1.265以降)の挙動です。v2.1.265には、管理側の要件がない端末でも、APIキーやカスタムヘッダーで認証するゲートウェイ構成でこのサインイン案内が出る不具合がありました。v2.1.266以降で直っています。

サブスクリプションでログインしていてもANTHROPIC_API_KEYが環境に残っていると、承認後はそちらが優先されます。組織が無効化したキーや期限切れのキーだと、これが認証エラーの原因になります。unset ANTHROPIC_API_KEYでサブスクリプションに戻し、/statusで有効な認証方式を確認します。

対話モードで初めて出るのは、APIキーを使うかどうかの承認です。選択は記憶され、あとから変えるには/configの「Use custom API key」を使います。このトグルはANTHROPIC_API_KEYが環境にあるあいだだけ現れます。非対話モード(-p)では、値があれば常にAPIキーが使われます。

claude auth statusで表示を確かめる

優先順位を文章で読むより、手元で見たほうが早い場面があります。claude auth statusは、ログイン状態を認証情報の出どころ付きで出すサブコマンドです。v2.1.285で、Claude Maxにログイン済みの手元に有効ではないダミー値(dummyなど)の環境変数だけを足して試しましたが、エラーにはなりませんでした。--textで人間向けの表示になり、指定しなければJSONです。

claude auth status --text
Login method: Claude Max account
Organization: <email>'s Organization
Email: <email>
ANTHROPIC_AUTH_TOKEN=dummy claude auth status --text
Auth token: ANTHROPIC_AUTH_TOKEN
ANTHROPIC_API_KEY=sk-ant-dummy claude auth status --text
Auth token: claude.ai · not in use
API key: ANTHROPIC_API_KEY

ANTHROPIC_AUTH_TOKENを足すと、サブスクリプションの3行が消え、変数名の1行だけになりました。ANTHROPIC_API_KEYだけを足した場合は、Auth tokenの行にclaude.aiのログインが「not in use」として残り、その下にAPI keyの行が付きました。両方を同時に足すと、Auth token: ANTHROPIC_AUTH_TOKENとAPI key: ANTHROPIC_API_KEYの2行が並び、「not in use」の印は出ませんでした。CLAUDE_CODE_OAUTH_TOKENを足したときも、Auth token: CLAUDE_CODE_OAUTH_TOKENの1行になります。

見えるのは選ばれた出どころの名前までです。値が有効かどうかは、この表示からは分かりません。JSON形式のほうにはapiKeySourceというフィールドがあり、ANTHROPIC_API_KEYを足したときは"ANTHROPIC_API_KEY"が入りました。同じ確認は、セッション内の/statusのAuth token・API keyの行でもできます。ゲートウェイ接続の確認手順でも、この行が「保存済みのclaude.aiログインではなく、ゲートウェイの資格情報が有効」の目印とされています。

--bareで読まれる変数

CIで--bareを使うスクリプトでは、読まれる変数が変わります。claude --helpの--bareの説明には、次の一文があります。

Anthropic auth is strictly ANTHROPIC_API_KEY or apiKeyHelper via --settings (OAuth and keychain are never read).

公式の環境変数一覧のCLAUDE_CODE_SIMPLE(--bareと同等)の説明も、ANTHROPIC_API_KEYか--settingsで渡すapiKeyHelperだけを挙げます。CLAUDE_CODE_OAUTH_TOKENは読まれないと、認証ガイドが明記しています。ANTHROPIC_AUTH_TOKENをこの経路で読むかどうかは、ヘルプにも公式ドキュメントにも記述がありません。ゲートウェイのBearerトークンを--bareで渡す構成は、実際に動かして確かめてから使う必要があります。

ゲートウェイ運用で起きること

ANTHROPIC_AUTH_TOKENやANTHROPIC_API_KEY、apiKeyHelperを有効にした環境には、認証以外の副作用もあります。公式のゲートウェイ接続ガイドには、次のような挙動が載っています。

  • Remote Controlと音声入力(voice dictation)は、claude.aiのIDに依存するため使えなくなります。Remote Controlは、ANTHROPIC_BASE_URLがAnthropic以外のホストを指すあいだも無効です。
  • 認証変数かヘルパーが有効で、ANTHROPIC_BASE_URLがゲートウェイを指しているとき、利用状況はConsoleの分析ダッシュボードに報告されません。テレメトリはゲートウェイの資格情報なしでAnthropicに送られます。
  • Bedrock・Google CloudのAgent Platform・Claude Platform on AWSのゲートウェイでは、独自のトークンも要るときANTHROPIC_AUTH_TOKENを足します。skip-auth変数は残します。skip-authが無いとAuthorizationヘッダーが取り除かれます。

Bearer以外の方式や別ヘッダーで認証するゲートウェイでは、どちらの変数でも合いません。その場合、公式はANTHROPIC_CUSTOM_HEADERSを使う方法を案内しています。

組織制限と資格情報の保管

管理設定でforceLoginOrgUUIDのような組織制限をかけると、環境変数やヘルパーの認証情報は起動時にブロックされます。対象はANTHROPIC_AUTH_TOKEN・ANTHROPIC_API_KEY・apiKeyHelperのすべてです。環境変数の認証情報は、どの組織に属するかを検証できないためです。forceLoginMethodの下でも、資格情報がサインインの代わりになってしまうため同じ扱いです。APIキー認証自体を組織が無効化しているケースはClaude Codeで組織がAPIキー認証を無効化したときの対処で扱っています。

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

適用されない面 — 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に持ち込んでも反映されない、という取り違えが起きやすいポイントです。

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

値にHTTPヘッダーへ入れられない文字が混ざっていると、Claude Codeはリクエストを送る前に検知して止めます。この検査が働くのは直接APIとLLMゲートウェイの経路で、Amazon Bedrockのようなサードパーティのクラウドでは送信前に走りません。対象は、改行、NULバイト、U+00FFを超える文字(曲がった引用符やゼロ幅スペースなど)です。文言の頭は、値の出どころで変わります。

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).

Invalid auth tokenは、ANTHROPIC_AUTH_TOKENとCLAUDE_CODE_OAUTH_TOKENのどちらでも出ます。頭の文言だけでは区別できないので、後ろの説明に出る変数名で見分けます。ANTHROPIC_API_KEY側の同じ問題は「Invalid API key · Fix external API key」で始まり、X-Api-Keyヘッダーの何文字目が問題かが続きます。位置と文字数は出ますが、値そのものは表示されません。チャットや文書からコピーしたときに、不可視文字が紛れていないかを疑う手がかりになります。

APIが実際にキーを拒否した場合(タイポや失効)も「Invalid API key」で、これはANTHROPIC_API_KEYだけでなくapiKeyHelperが返したキーの拒否でも出ます。公式が挙げる確認手順は、Consoleでキーが失効していないかを見ることと、env | grep ANTHROPICで環境に残っている変数を洗うことです。direnvやdotenv系のシェルプラグイン、IDEのターミナルが、プロジェクトの.envから古いキーを読み込んでいる例があるためです。

apiKeyHelperの出力は、このヘッダー検査を通りません。ヘルパーの出力にヘッダーへ入れられない文字があれば、実行時点で検証され「Your apiKeyHelper script is failing」になります。

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

関連する記事

Claude Code をもっと見る →