Claude Media
Claude Admin APIでシート・メンバー管理を自動化する
AnthropicClaude Codeチュートリアル

Claude Admin APIでシート・メンバー管理を自動化する

Admin APIでメンバーの一覧・招待・ロール変更・削除をcurlで実装し、オンボーディング/オフボーディングを自動化する手順です。シート数そのものの増減は対象外です。

読了目安 約17分

Admin APIは組織メンバーの一覧取得・招待・ロール変更・削除をエンドポイントとして提供しており、Team/Enterpriseプランのオンボーディングとオフボーディングをスクリプト化できます。ここでいう「シート管理」とは、契約シート数そのものを増減させる操作ではなく、組織メンバーというシートの占有状態をAPI経由で操作することです。この記事では、その境界を最初に明確にしたうえで、メンバーの一括CRUDをcurlで実装する手順をまとめます。

Admin APIで「シート管理」ができる範囲

Admin APIは組織メンバーの追加・変更・削除をエンドポイント化していますが、契約シート数自体を増減させるエンドポイントは持っていません。Team/Enterpriseプランでは、組織に所属するメンバーの数がそのまま請求対象のシート数になります。公式のTeam plan billing FAQsは「請求額は課金サイクル開始時点のメンバー数に基づく」「メンバーを追加すると日割りで即時課金される」「メンバーを削除しても返金やクレジットは発生せず、空いたシートはほかのメンバーへの再割り当てに使えるだけ」と説明しています。つまりメンバーを追加する操作が実質的な「シート追加」、削除する操作が実質的な「シートの空き作り」に対応します。

一方で、契約そのもののシート数(購入する枠の総数)を変更する操作は、Admin APIのどのエンドポイントにも存在しません。この操作は管理画面の「Organization and access」からしか行えず、Claudeのシート管理で扱っているUI操作が唯一の経路です。Admin APIで自動化できるのは「既存の枠に誰を割り当てるか」までで、「枠自体をいくつ用意するか」はAPIの対象外だと理解しておくと、実装の設計を誤りません。

前提 — 認証に使えるキーは3種類

Admin APIの呼び出しには、Admin APIキー(sk-ant-adminで始まる)・org:adminスコープ付きのOAuthベアラートークン・ワークスペースに紐づかない個人またはサービスアカウントキーのいずれかが必要です。Admin APIキーを発行できるのはAdminロールを持つメンバーのみで、org:adminトークンを取得できるのはAdmin・Owner・Primary Ownerロールに限られます。なお、Claude Enterprise(claude.ai)組織はこの3種類とは別経路で、claude.ai上で作成したスコープ付きAPIキーを使ってAdmin APIを呼び出します。この経路で適用されるのは組織メンバー(一覧・ロール変更・削除)と招待のエンドポイントで、ワークスペースやAPIキーの操作は対象外です。

curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/me" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

このリクエストが成功すれば、キーが組織スコープで有効なことを確認できます。CI等の非対話ワークロードから呼ぶ場合は、対話ログインではなくWorkload Identity Federation経由でトークンを発行する設計が推奨されています。

メンバー一覧を取得する

GET /v1/organizations/usersで組織の全メンバーを取得できます。

curl "https://api.anthropic.com/v1/organizations/users?limit=10" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

レスポンスにはメンバーごとのIDとメール、ロール(user / claude_code_user / developer / billing / admin)が含まれます。SDKのlistメソッドはページを自動取得するイテレータを返すため、limitは1ページあたりの件数を指定するだけで、全件を取り切るには自動ページングに任せます。curlで呼ぶ場合は1ページ分しか返らないので、大量のメンバーを扱うワークフローではSDK経由の実装が向いています。

新規メンバーを招待する — シートを埋める操作

メンバーの追加は招待という形を取ります。POST /v1/organizations/invitesにメールアドレスとロールを渡すと招待が作成され、相手が承諾すると組織メンバーになります。

curl "https://api.anthropic.com/v1/organizations/invites" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "email": "user@example.com",
    "role": "developer"
  }'

招待の有効期限は21日固定で、設定変更はできません。期限内に承諾されなかった招待は自動的に失効するため、一括招待バッチを組む場合は「送信から21日後に未承諾リストを再確認する」処理を組み込んでおくと取りこぼしを防げます。

ロールを変更する

既存メンバーのロールはPOST /v1/organizations/users/{user_id}で更新します。

curl "https://api.anthropic.com/v1/organizations/users/user_01XyDMpzjS89pFZXqSFUBDr6" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"role": "developer"}'

組織ロールはuser(プレイグラウンドのみ)/claude_code_user(プレイグラウンド+Claude Code)/developer(+APIキー管理)/billing(+請求管理)/admin(+メンバー管理)の5段階です。Admin以上のロールにはOwner・Primary Ownerも含まれ、これらのロールを持つメンバーへの操作は次の削除の節で扱う制限が関わってきます。

メンバーを削除する — シートを空ける操作

DELETE /v1/organizations/users/{user_id}でメンバーを組織から削除します。

curl -X DELETE "https://api.anthropic.com/v1/organizations/users/user_01XyDMpzjS89pFZXqSFUBDr6" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

Adminロールを持つメンバーはAPI経由では削除できません。先にロールをdeveloper等へ引き下げてから削除するか、管理画面から手動で対応する必要があります。この制限を知らずにオフボーディングスクリプトを組むと、退職者がAdminロールだった場合にだけ処理が失敗し、原因が分かりにくいバグになります。

削除後のAPIキーの挙動はキーの種類で異なります。個人キーは対象ユーザーの削除と同時に無効化されますが、サービスアカウントキーはサービスアカウント自体をアーカイブしない限り動き続けます。ワークスペースキーはメンバーの削除に関係なく動作を継続します。オフボーディングを徹底するなら、メンバー削除だけでなく、そのメンバーが発行した個人キー以外のキー(サービスアカウントキー・ワークスペースキー)も別途棚卸しする工程が要ります。

招待の一覧・削除も自動化できる

保留中の招待はGET /v1/organizations/invitesで一覧取得、DELETE /v1/organizations/invites/{invite_id}で個別に取り消せます。

curl "https://api.anthropic.com/v1/organizations/invites?limit=10" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

異動や採用計画の変更で招待自体が不要になったとき、一覧からstatusがpendingのものだけを抽出して取り消すバッチを組んでおくと、期限切れを待たずに招待枠の整理ができます。

一括CRUDワークフローを組む — 実装パターン

オンボーディング・オフボーディングを自動化する典型的な構成は、人事システムやSSOのグループ変更をトリガーに、次の3ステップをスクリプトで連結する形です。

フェーズ使うエンドポイントやること
入社時使うエンドポイントPOST /v1/organizations/invitesやること許可ドメインのメールへ招待を作成し、ロールを初期値で割り当てる
異動・昇格時使うエンドポイントPOST /v1/organizations/users/{user_id}やることロールをdeveloper⇔admin等に変更する
退職・契約終了時使うエンドポイントDELETE /v1/organizations/users/{user_id}やることメンバーを削除し、シートを空ける

このワークフローをCIやIdPのWebhookから叩く場合は、org:adminのOAuthトークンをWorkload Identity Federation経由で発行する構成にすると、対話ログインを介さずに済みます。人が直接Admin APIキーを扱う経路を減らすほど、キー漏洩時の影響範囲を絞り込めます。実際に誰が・いつ・どの操作をAPI経由で行ったかを追跡したい場合は、Claude Admin APIで監査ログは取れるかで扱っている監査ログの取得方法とあわせて設計してください。

入社者リストをCSVで受け取り、一括招待する最小構成はこのような形になります。

while IFS=, read -r email role; do
  curl -sS "https://api.anthropic.com/v1/organizations/invites" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d "{\"email\": \"${email}\", \"role\": \"${role}\"}"
  sleep 1
done < new_hires.csv

new_hires.csvは「メールアドレス,ロール」の2列で用意し、1行ずつ招待を作成します。sleepを挟んでいるのは、大量の招待を一度に送りつけてAPI側のレート制限に引っかかるのを避けるためです。オフボーディング側も同じ構造で、削除対象のユーザーIDリストをDELETEエンドポイントへ順番に投げる形にすれば、退職処理をスクリプト1本で完結できます。ただしAdminロールの対象者だけは前述のとおりAPI側で弾かれるため、実行後に失敗リストを必ず確認し、手動対応が必要な相手を洗い出す工程を残しておきます。

バッチ処理を再実行する可能性がある場合は、レスポンスのステータスコードで既存状態と新規作成を区別できるようにしておくと安全です。重複招待時の挙動はAPIのバージョンや状況で変わりうるため、実装前に一度実際にリクエストを送って挙動を確認しておき、事前に招待一覧を取得して重複チェックを挟むか、エラーレスポンスを「無視してよい失敗」として扱うかのどちらかを設計時に決めておきます。何も判定せずにリトライだけを繰り返す実装は、同じメンバーへの操作が重複して意図しない状態になる原因になります。

ここで扱っているのは組織全体のメンバーに対するロールです。ワークスペース単位のロール(workspace_admin等)は別のエンドポイントが管轄しており、混同すると意図しない範囲まで権限を変更してしまいます。ワークスペース単位の操作はClaude Admin APIでワークスペース管理を実装するにまとめているので、組織メンバーの追加・削除とあわせて設計するときは両方を参照してください。

よくあるつまずき

  • Adminロールのメンバーを削除しようとしてエラーになる: APIはAdminロールの削除を拒否します。先にロールを引き下げるか、管理画面から手動で対応します
  • 契約シート数を減らすつもりでメンバーを削除しても請求が変わらない: メンバー削除は空き枠を作るだけで、契約シート数自体の削減には別途管理画面での操作が必要です
  • 招待が21日で失効して気づかない: 有効期限は固定で延長できません。未承諾の招待を定期的に一覧取得して再送する運用が要ります
  • curlで一覧を取っても全件揃わない: curl・PHP・Rubyの実装は1ページ分しか返しません。全件が必要な自動化はPython/TypeScript等のSDKの自動ページング機能を使います
  • Claude Platform on AWS環境でメンバー管理エンドポイントが使えない: organization members・invites・API keysのエンドポイントは非対応です。使えるのはworkspaceとexternal_keys関連のエンドポイントのみで、メンバーのオンボーディング・オフボーディング自動化はAWS環境では別の方法が必要です

まとめ

Admin APIでの「シート・メンバー管理」は、組織メンバーの一覧取得・招待・ロール変更・削除という4操作の自動化を指し、契約シート数そのものの増減は含みません。オンボーディングは招待の作成、オフボーディングはメンバー削除に対応しますが、Adminロールの削除制限とキー種別ごとの失効挙動を踏まえておかないと、退職者対応が中途半端に終わります。契約シート数自体を変更したい場合はClaudeのシート管理のUI手順を、招待方式の詳細や権限設計そのものを見直したい場合はClaudeチームのメンバー管理を参照してください。

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

関連する記事

Anthropic をもっと見る →