Admin APIのworkspace_idがscopeに変わる — 2026-10-21の移行手順

API version 2026-10-21 では、Admin APIとClaude Enterprise Analytics APIの応答から、名前を変えたフィールドの旧名が消えます。壊れやすいのは、APIキーの workspace_id が null ならDefault Workspaceと読んでいるコードです。Analyticsの actor.email と、活動サマリーの summaries も同じ扱いです。

このページでは、どの旧名がどの新名に変わるか、null をどう読み替えるか、移行中に両対応で読む書き方を順に示します。

何が変わるか — 旧名と新名の対応

変更は「新しい版を指定したときの応答」に入ります。旧名が応答から外れ、新名だけが返ります。

Admin APIにはRBAC(役割ベースのアクセス制御)の改名もあり、全体は次の表のとおりです。

APIキー一覧を workspace_id で絞り込むクエリ指定は、変更の対象外です。

壊れるのは「新しい版を送った」ときだけ

旧名が消えるのは 2026-10-21 を指定したリクエストです。2023-06-01 のまま送るリクエストでは、移行ガイドが旧名の仕様を 2023-06-01 のものとして説明しています。何もしなければ、何も変わりません。

問題は、版が意図せず上がる経路です。

• SDKを使っている場合、リクエストの版は「そのSDKのメジャーバージョンが出た時点の最新版」になります。2026-10-21 を使う最初のメジャーはPythonの anthropic が2.0.0、TypeScriptの @anthropic-ai/sdk が1.0.0、Go SDKが2.0.0です。SDKを上げると、コードを触っていなくても応答の形が変わります。
• SDKを使わない場合は、anthropic-version ヘッダーを 2026-10-21 に書き換えた時点で切り替わります。

Admin APIやAnalytics APIを直接curlで叩いている運用スクリプトは、ヘッダーを書き換えない限り影響を受けません。逆に、Messages APIの改修でSDKを上げたついでに、同じSDKで組織管理の集計も回している構成では、集計側が先に壊れます。

APIキーのworkspace_idがnullだったときの読み替え

ここが一番、読み違えやすい変更です。旧版の workspace_id は、次の3つを区別できませんでした。

旧版では、Default Workspaceのキーと全ワークスペースのキーが、どちらも null でした。新しい版では前者に実IDが入るので、null を手がかりにしていたコードは次のように壊れます。

• workspace_id is None をDefault Workspaceの判定にしていた処理が、Default Workspaceのキーを素通しする。
• key["workspace_id"] を直接引いていると、キー自体が応答に無いため KeyError になる。
• 全ワークスペースのキーは scope に workspace_id が付かないので、scope["workspace_id"] を無条件に引いても同じエラーになる。

Default WorkspaceのIDを先に調べる

null で判定できなくなるので、Default WorkspaceのIDを別に持っておき、scope.workspace_id と比べます。IDは、List Workspacesに include_default=true を付けて呼び、名前が "Default" のワークスペースから取ります。

curl "https://api.anthropic.com/v1/organizations/workspaces?include_default=true" \
  -H "anthropic-version: 2026-10-21" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  | jq -r '.data[] | select(.name == "Default") | .id'

ワークスペース側の一覧の扱いはAdmin APIのワークスペース管理で、キーの種類と取得方法はAdmin APIキーの取得方法とスコープ選択で説明しています。

両方の版で動く読み方にする

SDKの更新を段階的に進めるなら、新旧どちらの応答でも同じ答えを返す関数を挟んでおくと、切り替えの日に差分が出ません。次はPythonでの例です(応答の形は移行ガイドの説明に沿った想定です)。

DEFAULT_WORKSPACE_ID = "wrkspc_..."  # List Workspacesで調べたID
 
 
def key_binding(key: dict) -> str:
    """APIキーの紐づき先を 'default' / 'organization' / ワークスペースID で返す"""
    if "scope" in key:  # 2026-10-21 の応答
        scope = key["scope"]
        if scope.get("type") == "organization":
            return "organization"
        ws = scope["workspace_id"]
    else:  # 2023-06-01 の応答
        ws = key.get("workspace_id")
        if ws is None:
            return "default"  # 旧版では全ワークスペースのキーも null になる点に注意
    return "default" if ws == DEFAULT_WORKSPACE_ID else ws

旧版の分岐にある null は、Default Workspaceのキーでも全ワークスペースのキーでもあり得ます。旧版の応答だけでは区別できないので、旧版を読む期間は、この関数の "default" を「Default Workspaceまたは全ワークスペース」と扱ってください。新しい版に揃えてから、厳密な判定に切り替えます。

使用量・コストレポートの group_by[]=workspace_id と、そこで null がDefault Workspaceを指す読み方は、移行ガイドの変更表に載っていません。レポート側の読み方はUsage and Cost APIの解説のままで、変わるのはAPIキーのオブジェクトです。

Analytics APIのactor.emailとsummaries

Analytics APIの変更は、名前の置換だけで済みます。

actor.email を取り出していたjqは、新しい版でメールアドレスの列だけが空になります。例外で落ちないぶん、気づきにくい壊れ方です。

# 移行前
jq -r '.data[] | [.actor.email, .total_tokens] | @csv'
 
# 移行後
jq -r '.data[] | [.actor.email_address, .total_tokens] | @csv'

上の .data[] は、ユーザー別レポートの行を取り出す書き方の一例です。ほかのキー名はuser_usage_reportの解説やuser_cost_reportの解説に沿って読んでください。活動サマリーは最上位の summaries が data になるので、.summaries[] と書いていた箇所を .data[] に直します。メンバー別・グループ別の取得はAnalytics APIのusersの解説が扱っています。

Analyticsのキーは、Admin APIキーとは別物です。Admin APIキーではAnalytics APIを呼べず、Analyticsキーでもその逆はできません。変更表には両方のAPIが並びますが、棚卸しは別々のキーを使うスクリプトごとに行います。

RBACとレート制限の読み取りコードの直し方

こちらも名前の置換が中心です。ただし group_type だけは、フラットなキーが入れ子に変わります。応答の group_type は group.type になるので、jqなら .group_type を .group.type に、Pythonなら item["group_type"] を item["group"]["type"] に直します。リクエスト側の ?group_type= は変わらないため、URLは触りません。

RBACは3か所です。グループの取得・更新で読んでいる roles は role_ids に、メンバー一覧と追加の応答にある group_id は rbac_group_id になります。ロールの一覧で表示名として使っていた name は display_name です。

# 移行前
jq -r '.data[] | [.name, .group_type] | @csv'
 
# 移行後(レート制限の応答。ロール一覧なら .display_name)
jq -r '.data[] | [.group.type] | @csv'

name は多くの応答にある一般的な語なので、置換はロール一覧を読む箇所だけに限ります。ワークスペース一覧の name(前節でDefault Workspaceを探すのに使いました)は、変更表に載っていません。

移行前に洗い出す3つの場所

置換は文字列検索で拾えます。次の語を、リポジトリと運用スクリプトに対して検索してください。

grep -rnE "workspace_id|actor\.email|\.summaries|\"summaries\"|group_type|\"roles\"|group_id" \
  --include='*.py' --include='*.ts' --include='*.js' --include='*.sh' --include='*.sql' .

ヒットした行は、次の3種に分けると作業が早く進みます。

1. APIキーのオブジェクトを読んでいる: workspace_id を scope に読み替える。null を意味づけしている行が最優先。
2. Analyticsの応答を読んでいる: actor.email と summaries を置換する。ダッシュボードのSQLや、BIツールへの取り込み設定も対象。
3. 名前が同じだけで別物: 使用量レポートの group_by[]=workspace_id やAPIキー一覧の絞り込みのクエリ。これらは変更表に載っていないので触らない。

workspace_id は応答のフィールドにも、クエリにも、レポートの集計軸にも出てくる語です。検索の件数が多くなりますが、直すのは「APIキーの応答を読む箇所」だけです。

移行を急がない選択もある

旧名が消えるのは新しい版を指定したときです。Admin APIの改名のためだけに、急いでSDKを上げる必要はありません。反対に、Messages APIで temperature などのサンプリングパラメータが外れるなど、同じ版に別の破壊的変更も入っています。SDKを上げるなら、Admin API側の読み方と同じリリースで直します。

次の順で進めると、切り替え時に何が起きたかを切り分けやすくなります。

移行の副産物もあります。旧版では null に混ざっていた「全ワークスペースで使えるキー」を、scope で単独に数えられます。キーの棚卸しで、影響範囲の広いキーを先に洗い出せます。

よくある質問

旧名と新名を同時に返してもらう設定はありますか

移行ガイドに、新旧を同時に返す設定の記載はありません。切り替えは anthropic-version で行います。

Default Workspaceのキーは、新しい版で見分けがつきますか

つきます。Default Workspaceに固定したキーは scope.workspace_id に実IDが入るので、List Workspacesで調べたIDと一致するかどうかで判定できます。全ワークスペースのキーは scope が {"type": "organization"} で、IDは付きません。