Admin APIがclient.organizationへ — beta卒業の移行手順

Admin APIの主要メソッドは、2026年9月30日のSDKリリースでbetaを外れました。呼び出し先は client.beta.organization から client.organization に、CLIは ant beta:organization から ant organization に変わります。

名前は単数形の organization です。client.organizations と複数形で書くと動きません。旧い呼び出し先も同じリリースに残っているため、今すぐ壊れる箇所はありません。このページでは、書き換える範囲、メンバー操作で名前が変わる点、betaのまま残るAPIとの見分け方を順に示します。

どのSDKから使えるか

リリースノートによると、次のバージョンで対象のメソッドがbetaを卒業しました。

対象は、組織情報、メンバー、招待、ワークスペース、APIキー、レート制限、サービスアカウント、Workload Identity Federation(WIF)、顧客管理の暗号鍵(CMEK)、コンプライアンス設定のメソッドです。これらの下位リソースは、まとめて client.organization の下に移りました。

古いバージョンのSDKでは client.organization が存在しません。書き換えの前に、依存を上のバージョン以上に上げます。

呼び出し先はこう変わる

言語ごとの綴りは、Admin APIのページが次のように示しています。

betaの時期は、この organization の前に beta が挟まっていました。外す差分は1語だけです。

client.beta.organization.workspaces.members.add(...)

client.organization.workspaces.members.add(...)

CLIも同じです。コロンでつなぐリソース名の先頭から beta: を取ります。

# 旧: ant beta:organization:workspaces:members add ...
ant organization:workspaces:members add \
  --workspace-id wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ \
  --user-id user_01WxYzAbCdEfGhJkMnPqRsTu \
  --workspace-role workspace_developer

上のコマンドは、Admin APIのページに載っている例に沿った形です。IDは例示用の値なので、自分の組織のものに置き換えます。

メンバー操作はmembersではなくusers

名前が一致しない場所が1つあります。組織メンバーの一覧・更新・削除は、client.organization.members ではなく client.organization.users です。CLIでも ant organization:users list のように users を使います。

import anthropic
 
client = anthropic.Anthropic()
 
# 組織メンバーの一覧(イテレーターが必要に応じて次のページを取得する)
for user in client.organization.users.list(limit=10):
    print(user.id)

一方、ワークスペースのメンバーは workspaces.members です。「メンバー」という日本語に引きずられて organization.members と書くと、存在しないリソースを呼ぶことになります。

Admin APIのページに現れる、主なリソース名は次のとおりです。

リソース名の綴りは、言語の命名規則に合わせて変わります。同じ「APIキーの一覧」でも、各言語の書き方は次のとおりです。

Pythonの api_keys をそのまま他の言語へ写すと、TypeScriptやJavaでは動きません。各言語のタブの例を見て書きます。

呼び出し先だけでなく、引数の渡し方も言語ごとに違います。ワークスペースにメンバーを加える add は、Admin APIのページで次のように書かれています。

const member = await client.organization.workspaces.members.add(
  "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
  {
    user_id: "user_01WxYzAbCdEfGhJkMnPqRsTu",
    workspace_role: "workspace_developer"
  }
);

Goでは、client.Organization.Workspaces.Members.Add( にコンテキストとワークスペースIDを渡し、anthropic.OrganizationWorkspaceMemberAddParams でユーザーIDとロールを指定します。PHPは $client->organization->workspaces->members->add( を呼び、名前付き引数でワークスペースIDとユーザーIDを渡します。Rubyではロールがシンボル(:workspace_developer)で、C#では列挙型の NoBillingWorkspaceRole.WorkspaceDeveloper を渡します。TypeScriptの user_id のようなスネークケースのキーが、Goでは UserID に変わる点も、置換だけでは直せない差です。

表に載せなかった分野もあります。サービスアカウント(svac_...)、フェデレーションの発行者(fdis_...)とルール(fdrl_...)は、org:admin のOAuthトークンだけを受け付けるエンドポイントです。レート制限はRate Limits API、コンプライアンス設定はCompliance APIで扱います。CMEKは外部鍵(/v1/organizations/external_keys)のエンドポイントです。Admin APIのページには、これらの分野のSDK上の綴りを示す例がありません。書き換える前に、各分野のページか使っているSDKのリファレンスで綴りを確かめます。

旧名は残っている — だからこそ棚卸しが要る

リリースノートには、これらのリリースが client.beta.organization と ant beta:organization も引き続き備える、とあります。つまり、書き換えを後回しにしても、動いているスクリプトは動き続けます。

ただし、旧名をいつまで残すかはリリースノートに記載がありません。提供終了の時期が示されていないため、SDKを更新するたびに旧名が残っていないかを確かめることになります。新規に書くコードは新しい呼び出し先で書き、既存コードは更新のついでに寄せる、という進め方が現実的です。

既存コードの洗い出しは、beta を含む呼び出しを検索するだけで済みます。

# Python / TypeScript / Ruby の呼び出しを探す
grep -rn "beta\.organization" --include="*.py" --include="*.ts" --include="*.rb" .
 
# CLIを使っているシェルスクリプトやCIの設定を探す
grep -rn "ant beta:organization" .

ここで注意したいのは、ヒットした全部を置換してよいわけではないことです。次の節で、betaのまま残すものを見分けます。

すべてが卒業したわけではない

置換の前に、対象のAPIかどうかを確認します。卒業したのは、先に挙げた10分野のメソッドです。同じ organization の名前空間でも、別のAPIはbetaのまま提供されています。

• Claude Tag API: 2026年10月23日のリリースノートで、experimental-claude-tag-2026-10-21 ヘッダーつきのbetaと説明されています
• 組織のWebhook: 2026年10月20日のリリースノートで、webhooks-2026-10-07 ヘッダーつきのbetaと説明されています
• Usage and Cost Analytics API: analytics-usage-cost-2026-08-24 ヘッダーつきのbetaです

これらはbetaヘッダーを付けて呼ぶAPIです。beta を含む行を機械的に置換すると、卒業していないAPIまで巻き込みます。一括置換は避け、1行ずつ対象を確かめます。

組織向けのPlugins管理は、Plugins APIの組織向けガイドにまとめています。

書き換えで見落としやすい3か所

ヘッダーを手で付けていたコード

betaの時期にヘッダーを自分で付けていたコードは、卒業後もそのヘッダーを送り続けます。Claude Enterpriseのユーザー管理の件では、リリースノートが「このヘッダーはグループとカスタムロールのリクエストで不要になり、まだ送っていても変更なしで受け付けられる」と書いています。ヘッダーは外しても残しても動くため、呼び出し先の書き換えと同時に整理すると、後で迷いません。

SDKのバージョンを固定している環境

CIやコンテナで、SDKを古いバージョンに固定している場合があります。固定を上げないまま client.organization に書き換えると、卒業前のバージョンにはその呼び出し先がありません。書き換えの変更と、依存の更新は同じ変更にまとめます。

別の移行と取り違えない

この記事の移行は、SDKのどこを呼ぶかの話です。APIバージョン 2026-10-21 で、応答のフィールド名が変わる移行とは別の作業です。フィールド名の側はAdmin APIのフィールド名変更で、APIバージョンの指定とSDKのメジャーバージョンの関係はAPIバージョン2026-10-21への移行手順で扱っています。両方に当たる場合は、呼び出し先を寄せたあとで、フィールド名の読み替えに進むと切り分けやすくなります。

認証は移行の対象外

呼び出し先が変わっても、認証の扱いは変わりません。Admin APIは、sk-ant-admin... で始まるAdmin APIキー、org:admin スコープのOAuthトークン、ワークスペースに紐づかない個人キーまたはサービスアカウントキーのいずれかを受け付けます。SDKとCLIは ANTHROPIC_AUTH_TOKEN を自動で読むので、OAuthトークンで呼ぶ場合は同じシェルの ANTHROPIC_API_KEY を空にしておきます。キーが残っていると、トークンではなくキーが送られます。

CLIでトークンを取る手順は、Admin APIのページでは次の2行です。専用のプロファイルに org:admin を保存してから、アクセストークンを環境変数へ出します。

ant auth login --profile admin --scope "org:admin"
export ANTHROPIC_AUTH_TOKEN=$(ant auth print-credentials --profile admin --access-token)

対話ログインのトークンは短命です。書き換え後に401が返り始めたら、呼び出し先ではなくトークンの期限切れを疑います。上の export の行を実行し直すと、新しいトークンに差し替わります。トークンの権限は組織全体に及ぶので、保管先にも気を配ります。

使えない環境の確認

Admin APIには、組織の種類による制限があります。呼び出し先を変えても、使えないエンドポイントが使えるようにはなりません。

• 個人アカウントでは、Admin APIは使えません
• Claude Platform on AWSでは、ワークスペース、外部鍵(CMEK)、テレメトリ送信先、Usage and Cost Analyticsのエンドポイントだけが使えます。組織メンバー、招待、APIキー、レート制限の報告は使えません
• Claude Enterprise(claude.ai)の組織は、スコープ付きAPIキーで呼びます。Admin APIのページによると、メンバーと招待のエンドポイントが対象です

サービスアカウントやフェデレーションの発行者・ルールのエンドポイントは、org:admin のOAuthトークンだけを受け付けます。管理用のキーでは通らないため、WIFの設定を書き換える場合は、認証の方式も一緒に確認します。操作の流れはWIFをAdmin APIで管理する手順にあります。

まとめ

呼び出し先を変えるのは、beta を1語外すだけの作業です。手間がかかるのは、users と members の取り違え、betaのまま残るAPIの切り分け、SDKの依存更新の3点です。旧名は残っているので、期限に追われる移行ではありません。

次のSDK更新で旧名を外されても困らないよう、新規のコードから client.organization で書き始めるのが無理のない進め方です。