# Claude API 2026-10-21移行のゲートウェイ設計

> Claude API 2026-10-21で何が壊れるか。sampling除去・Bearer認証・Admin APIのフィールド改名を、ゲートウェイと段階移行の設計で整理する。

- Canonical: https://kuucorp.com/blog/claude-api-version-2026-10-21-enterprise-migration-design/
- Date: 2026-10-24
- Last modified: 2026-10-24
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
2026年10月21日、Claude APIに新しいAPIバージョン `2026-10-21` が加わった。`2023-06-01` 以来の更新で、`temperature` を送るだけで400エラーになる。複数チームがSDKを使い、社内ゲートウェイや監視基盤がヘッダーを読んでいるエンタープライズでは、各チームが個別にSDKを上げるだけでは安全に移行できない。本稿は公式の移行ガイドに沿って、基盤チームが先に押さえる変更点と段階移行の設計を整理する。

## 2026-10-21でMessages APIの何が壊れるのか

> 2026-10-21ではtemperature等の送信と、assistantへのdocument配置が400エラーになります。

Messages API（`POST /v1/messages`）、トークンカウント、Message Batchの各リクエストに次の3つが適用される。

- **サンプリングパラメータの除去**: `temperature`、`top_p`、`top_k` は既定値でも400になる。最新メジャーのSDKとCLIからはこの3つの引数自体がなくなった
- **assistantメッセージ内のdocumentブロック**: 400になる。documentはuserメッセージで送る。web fetchツール結果のようにブロックの内側にあるdocumentは従来どおり受理される
- **userメッセージのtextブロックに付けたcitations**: 空でない `citations` 配列は400になる。assistant側の `citations` と、documentや検索結果の `"citations": {"enabled": true}` は有効なまま

注意すべきは挙動の変化だ。送信をやめた場合の値は既定値（`temperature` は1.0）になる。Claude 4.7以降のように既定値しか受け付けないモデルは変わらないが、Claude Sonnet 4.6のように別の値を受け付けるモデルで出力の安定化のために `temperature` を下げていた呼び出しは、その効果を失う。代替設定は用意されていない。

## APIキーのヘッダー変更でゲートウェイは何を直すのか

> 新SDKはAPIキーをAuthorization: Bearerで送るため、X-Api-Keyを読むゲートウェイは修正が必要です。

SDKとCLIは、キーを `Authorization: Bearer <key>` で送る。Claude API側はどちらのヘッダーのキーも受理するため、API自体は止まらない。壊れるのは自社側の層だ。

- `X-Api-Key` を読んでチーム識別や課金按分をしているプロキシ・LLMゲートウェイ
- `X-Api-Key` をマスクしているログフィルタ、監視、テストスタブ
- リクエスト単位で `X-Api-Key` を上書き・削除していたコード。新SDKでは上書きしても両方のキーが送られ、削除しても効かない

一方、SDKクライアントが保持する資格情報は1つになった。APIキーと認証トークンが同じヘッダーを使うためで、Python SDKではコンストラクタに2つ以上渡すと `ValueError` になる。ゲートウェイ側は `Authorization` と `X-Api-Key` の両方を読む期間を設けてから、`X-Api-Key` 依存を外す順序が安全だ。構成の考え方は[LLMゲートウェイの設計](/blog/llm-gateway-routing-rate-limiting/)も参考になる。

## Admin APIのフィールド名変更はどこに影響するのか

> Admin APIの応答からrolesなど旧フィールド名が消えるため、棚卸しや集計コードの修正が必要です。

2026-10-21の応答からは旧名が消える。基盤チームのメンバー管理・コスト配賦の自動化に直撃する。

| 対象 | 旧名 | 新名 |
|---|---|---|
| RBACグループ | `roles` | `role_ids` |
| RBACグループメンバー | `group_id` | `rbac_group_id` |
| RBACロール | `name` | `display_name` |
| レート制限 | `group_type` | `group.type` |
| APIキー | `workspace_id` | `scope` |
| Analytics（ユーザー別） | `actor.email` | `actor.email_address` |
| Analytics（サマリー） | `summaries` | `data` |

最も落とし穴が大きいのはAPIキーだ。旧版の `workspace_id` が `null` だったキーは「Defaultワークスペース」か「全ワークスペース共通」かの区別がつかなかった。新版では `scope.workspace_id` に実IDが入り、全ワークスペース共通キーは `scope` が `{"type": "organization"}` になる。`null` をDefault扱いしていた棚卸しスクリプトは、`scope.workspace_id` をDefaultワークスペースのIDと比較する形に書き換える。ワークスペース統制の全体像は[ワークスペース管理とWIF](/blog/claude-api-workspace-team-management-wif/)で扱っている。

## どう段階移行を設計するべきか

> 移行は基盤層の先行修正、SDK更新、チーム別検証の順に進め、旧版に残す例外を管理します。

APIバージョンはSDKのメジャーバージョンと連動する。Python 2.0.0、TypeScript 1.0.0、Go 2.0.0（モジュールパスは `/v2`）、Java 3.0.0、`ant` CLI 2.0.0 などが初めて `2026-10-21` を既定で送る。SDKを使わない場合は `anthropic-version` ヘッダーを自分で指定する。

1. **インベントリ**: SDKのバージョン、`temperature` 系の送信箇所、`X-Api-Key` 依存、Admin API利用スクリプトを全チームから洗い出す
2. **基盤層の先行対応**: ゲートウェイとログ基盤を両ヘッダー対応にし、Admin API連携を新フィールド名に切り替える
3. **例外の明示**: 非既定の `temperature` が必須の呼び出しは、そのリクエストだけ `2023-06-01` に残せる。例外はチケットと期限で管理する
4. **Amazon Bedrockの扱い**: `2026-10-21` はClaude 4.7以降のモデルでのみ利用できる。旧モデルを呼ぶ経路は現行のSDKとバージョンを維持し、先にモデルを移す
5. **テスト**: 本番切替前に `2026-10-21` で統合テストを回す

旧版の廃止期限は、確認した公式資料に記載がなかった。期限が公表されるまでは、例外を放置せず棚卸しを続ける運用が妥当だ。全社規模のAI基盤変更管理は、Kuuの[大企業向けAI変革プログラムRDE](https://kuucorp.com/services/rde/)でも支援している。

## 参考

- [Migrating to API version 2026-10-21（Claude Platform Docs）](https://platform.claude.com/docs/en/api/migration-2026-10-21)
- [Claude Platform release notes](https://platform.claude.com/docs/en/release-notes/overview)

## まとめ

壊れるのは、サンプリング引数の送信、`X-Api-Key` 依存、Admin APIの旧フィールド名の3点に集約できる。基盤チームが先に両ヘッダー対応と新フィールド対応を済ませ、各チームのSDK更新を安全に受け止める順序を取れば、全社移行の手戻りは小さくなる。移行計画の設計や統制の整備は、[RDE](https://kuucorp.com/services/rde/)からお問い合わせください。
