SDKのX-Api-KeyがAuthorization Bearerに変わった — ゲートウェイの直し方

API version 2026-10-21 に対応した新メジャーのSDKとant CLIは、APIキーを X-Api-Key ではなく Authorization: Bearer <key> で送ります。社内のプロキシやゲートウェイが X-Api-Key を見てキーを取り出していると、SDKを上げた途端に認証が通らなくなります。

直し方は2通りです。ゲートウェイ側を Authorization も読むように変えるか、SDK側で X-Api-Key を自分で付けて戻します。CLIだけは戻す手段がなく、ゲートウェイ側を直すしかありません。

何が変わったのか

移行ガイドの該当節は、変更を1つの差分で示しています。

# Before
X-Api-Key: <key>
 
# After
Authorization: Bearer <key>

対象は ANTHROPIC_API_KEY と、コードで渡す api_key / apiKey の両方です。ant CLIでは --api-key-stdin で渡したキーも同じ扱いになり、--debug のログも Authorization: Bearer <REDACTED> に変わります。

Claude API自体はどちらのヘッダーも受け付けます。APIの概要ページでも、Authorization が基本で、x-api-key は旧来の代替として引き続き使えると書かれています。つまり壊れるのはAPIではなく、間に挟まる自前のコードです。

SDKを使わずcurlなどで直接呼ぶ場合は、この変更の対象外です。移行ガイドのcURLの例も、anthropic-version: 2026-10-21 を付けたうえで x-api-key ヘッダーのまま書かれています。ゲートウェイを通る経路のうち、SDK経由のものだけがヘッダーを変えると考えると、影響範囲を絞れます。

見直す場所は次のとおりです。

• X-Api-Key を読んで認証・課金の振り分けをするゲートウェイやリバースプロキシ
• 同じヘッダーを読むミドルウェア、ログのマスキング、テスト用のスタブ
• X-Api-Key を付け外ししている呼び出しコード

ログのマスキングは見落としやすい箇所です。マスク対象が X-Api-Key だけだと、新しいSDKのキーが載る Authorization ヘッダーはマスクの対象外になります。

どの言語のSDKが対象か

Python、TypeScript、C#、Go、Java、PHP、RubyのSDKとant CLIが対象です。必要なバージョンは、ガイドの手順どおり次のとおりです。

SDKを上げる前は、リクエストはそれまでのAPIバージョンで送られます。ゲートウェイ側の影響が出るのは、このメジャー更新を適用した環境からです。

Foundryだけはx-api-keyのまま

クラウド経由のクライアントは一括りにできません。移行ガイドの記述は次のとおりです。

• Foundry: Pythonの AnthropicFoundry、TypeScriptの @anthropic-ai/foundry-sdk、Goの foundry.ClientConfig、Javaの FoundryBackend、PHPの Anthropic\Foundry\Client は、これまでどおり x-api-key で送る
• Bedrock Mantle(各言語のMantle系クライアント): もともとBearerトークンで、変更なし
• BedrockのTypeScript SDK: apiKey はもともとBearerトークン
• AWS向けクライアント: ANTHROPIC_AWS_API_KEY などのキーは、通常のクライアントと同じくBearerに変わる

つまり、同じ社内ゲートウェイの背後にFoundry用とAnthropic直結用のクライアントが混在していると、片方は x-api-key、もう片方は Authorization で来ます。ゲートウェイは両方を読める形にしておくのが安全です。

ゲートウェイ側を直す

根本的な直し方は、キーの取り出しを Authorization: Bearer に対応させることです。X-Api-Key を残したまま両対応にしておけば、移行の途中で旧SDKと新SDKが同時に動いていても通ります。

次はPythonで書いた取り出し処理の一例です(公式のサンプルではなく、考え方を示すための例)。

def extract_api_key(headers: dict[str, str]) -> str | None:
    auth = headers.get("authorization", "")
    if auth.lower().startswith("bearer "):
        return auth[7:].strip()
    return headers.get("x-api-key")

注意点が2つあります。

1. ゲートウェイが独自のトークンを Authorization で受けていると、そこにAPIキーが重なります。その場合は次の節のとおり、移行ガイドが示す構成に寄せます
2. ゲートウェイがAPIへ転送するとき、Authorization を残すか X-Api-Key に付け替えるかを決めます。APIはどちらも受け付けるので、付け替えは必須ではありません

動作確認は手元のエコーサーバーで

本番に当てる前に、SDKがどのヘッダーで送るかを手元で確かめられます。ヘッダーを表示するだけの小さなサーバーを立て、ANTHROPIC_BASE_URL をそこへ向けます。

python3 - <<'PY' &
from http.server import BaseHTTPRequestHandler, HTTPServer
 
class H(BaseHTTPRequestHandler):
    def do_POST(self):
        print({k: v for k, v in self.headers.items()
               if k.lower() in ("authorization", "x-api-key")})
        self.send_response(401); self.end_headers()
 
HTTPServer(("127.0.0.1", 8787), H).serve_forever()
PY
export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
export ANTHROPIC_API_KEY=sk-test

この状態でSDKから1回呼ぶと、旧SDKでは x-api-key だけ、新SDKでは authorization だけが表示される想定です。Authorization と X-Api-Key が両方出たら、後述の「両方送る構成」か、コードのどこかで手動付与しているヘッダーが残っています。

SDK側でX-Api-Keyに戻す

ゲートウェイを今すぐ直せないときは、SDK側でヘッダーを戻します。言語ごとに方法が違い、extra_headers に頼らないものがあります。

Python

HTTPクライアントの auth 関数で、Authorization を外して X-Api-Key に付け替えます。リトライのたびに毎回実行されます。

import httpx2
from anthropic import Anthropic, DefaultHttpxClient
 
 
def send_x_api_key(request: httpx2.Request) -> httpx2.Request:
    if request.headers.get("Authorization") == f"Bearer {api_key}":
        del request.headers["Authorization"]
        request.headers["X-Api-Key"] = api_key
    return request
 
 
client = Anthropic(api_key=api_key, http_client=DefaultHttpxClient(auth=send_x_api_key))

AsyncAnthropic では同じ関数を DefaultAsyncHttpxClient(auth=send_x_api_key) に渡します。

TypeScript

defaultHeaders に X-Api-Key を足し、Authorization: null でBearer側を止めます。

const client = new Anthropic({
  apiKey,
  defaultHeaders: { "X-Api-Key": apiKey, Authorization: null }
});

プロキシが認証情報を付ける構成で、クライアント側に何も持たせたくないときは、旧版では "X-Api-Key": null か Authorization: null のどちらでも指定できました。新版で有効なのは Authorization: null だけです。

Go・Java・C#・PHP・Ruby

• Go: option.WithHeader("X-Api-Key", apiKey) と option.WithHeaderDel("Authorization") を併用する。環境変数のキーも送られないようにするための削除
• Java: apiKey を呼ばず、ビルダーの putHeader("X-Api-Key", apiKey) で渡す
• C#: ApiKey と AuthToken を null にして、ExtraHeaders に X-Api-Key を入れる
• PHP: ミドルウェアで Authorization を外して X-Api-Key を付ける。クライアントの extraHeaders は使わない。リクエスト側に extraHeaders があるとクライアントの設定が置き換わり、betaの各エンドポイントが持つbetaヘッダーとも衝突するため
• Ruby: ミドルウェアで同様に付け替える。Anthropic::AWSClient は middleware: 引数を取らないので、リクエストごとに request_options: {middleware: ...} で渡す

ant CLIは戻せない

ant には独自ヘッダーを足すフラグも環境変数もないため、X-Api-Key で送らせる手段がありません。--base-url や ANTHROPIC_BASE_URL でゲートウェイへ向けているなら、ゲートウェイ側を Authorization から読むように直す必要があります。

なお --api-key と --auth-token のフラグ自体も削除されました。渡していると flag provided but not defined で止まります。ANTHROPIC_API_KEY か --api-key-stdin に切り替えます。

同じヘッダーを使う落とし穴

Authorization が認証トークンと共用になったことで、リクエスト単位のヘッダー操作が意図どおりに動かなくなりました。

キーを外す書き方が効かなくなる

X-Api-Key を消してトークンだけを送っていたコードは、Python・TypeScript・Go・PHP・Rubyに影響します。

ただしトークンだけを送らせる目的で消していたなら、移行ガイドは「書き換えずにそのコードを削除する」ことを勧めています。Authorization を消すとトークンまで消えるためです。

別のキーを足すと両方が出ていく

リクエストごとに別のキーを X-Api-Key で渡していた場合、新SDKでは置き換わらず、クライアントのキーと両方が送られます。Pythonなら extra_headers={"Authorization": f"Bearer {other_key}"} に、Goなら option.WithAPIKey(other_key) に変えます。

APIは1リクエストに1つの認証情報を前提にしています。両方が出ていく状態は、ゲートウェイがどちらを優先するか次第で挙動が変わるため、テストで見つけておく項目です。

1つのクライアントは1つの認証情報しか持たない

もう1つ、同時に入った変更があります。旧SDKはAPIキーと認証トークンの両方を持っていると、それぞれ別のヘッダーで両方を送っていました。同じヘッダーを共有するようになったため、新SDKのクライアントは認証情報を1つしか持てません。

• Pythonは、コンストラクタに複数を渡すと ValueError
• TypeScriptは TypeError
• Goはそのクライアントの全リクエストがエラー
• Rubyは ArgumentError

引数を渡さずに環境変数で解決させる場合は、優先順位の最上位が ANTHROPIC_API_KEY で、次が ANTHROPIC_AUTH_TOKEN です。両方がセットされていると警告が1回出て、キーが使われます。

ゲートウェイ用トークンとAPIキーを両方送りたいとき

ゲートウェイ向けのトークンと、その先のAPI向けのキーを両方送っていた構成は、そのままでは動きません。移行ガイドの指定は次の形です。

• トークンを auth_token / authToken で渡す
• APIキーは default_headers / defaultHeaders で X-Api-Key に入れる
• ゲートウェイは、転送前に自分の Authorization ヘッダーを取り除く

Claude APIは1リクエストに1つの認証情報を求めるので、ゲートウェイが Authorization を外さずに転送すると、APIには2つの認証情報が届きます。

環境変数が残っているとフェデレーションを隠す

認証情報を引数で渡さないクライアントは、決まった順に探します。Workload Identity Federationの資料では、コンストラクタ引数が最優先で、2番目が ANTHROPIC_API_KEY または ANTHROPIC_AUTH_TOKEN です。この2つは、後ろにあるプロファイルやフェデレーションの設定を丸ごと隠すと書かれています。

ゲートウェイの移行でBearerトークン方式やフェデレーションに寄せる場合は、古い ANTHROPIC_API_KEY を環境から外しておかないと、新しい設定が使われません。名前付きプロファイルを指定したのに存在しないときは、次の候補へ進まずエラーになります。

切り替えの順序

SDKを先に上げると、ゲートウェイが対応していない間は認証が止まります。次の順で進めると安全です。

ブラウザからAPIキーを直接送る構成を使っている場合は、ヘッダーの違いより前に、キーの露出自体を見直す必要があります。詳しくはdangerouslyAllowBrowserエラーの原因にあります。社内プロキシ越しの認証要件を別の面で整理した記事としては、MCP tunnelsリファレンスも参考になります。