Claude User Management APIでメンバー管理を実装する

User Management APIで何が操作できるか

User Management APIは、Claude Enterprise(claude.ai)組織の人とグループをプログラムから操作するためのAPIです。メンバーの一覧・ロール変更・削除、招待の送信・取り消し、グループの作成とメンバー管理、カスタムロールの参照までをカバーします。

独立した別のAPIではありません。Admin APIのうち /v1/organizations/users /v1/organizations/invites /v1/organizations/rbac_groups /v1/organizations/rbac_roles 系のエンドポイントを指す呼び名です。到達にはAdmin APIキーを使います。契約している組織の種類によって、使える範囲が次のように分かれます。

グループとカスタムロールのリクエストでは、ベータヘッダー anthropic-beta: ce-user-management-2026-07-13 を付けなくても動きます。付けたリクエストも受理され、挙動は変わりません。

最初の1本を通す — スコープとキーの確認

呼び出すエンドポイントによって必要なスコープが変わります。メンバー・招待のGETと全カスタムロールエンドポイントには read:members が必要です。メンバー・招待のPOST/DELETEは write:members です。グループのGETは read:rbac_groups、POST/DELETEは write:rbac_groups です。カスタムロール専用のスコープは無く、read:members で読みます。

read:org_audit スコープを持つキーは、ここで扱うGETエンドポイントのすべてと、Compliance APIの読み取りエンドポイントを呼べます。監査連携用の読み取り専用キーとして使う余地があります。キーの作成手順とスコープの選び方はClaude Admin APIキーの取得方法とスコープ選択にまとめています。

キーのスコープは作成後に変更できません。足りないスコープは、新しいキーを作って補います。呼び出しがキーのスコープを超えると403 Forbiddenで返り、キーが持つスコープとエンドポイントが要求するスコープがメッセージに並びます。

すべてのリクエストで x-api-key と anthropic-version の2つのヘッダーが必要です。まず一覧を1回引いて、キーとスコープが通るかを確かめます。

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

応答は data 配列と、ページ送り用の has_more first_id last_id で構成されます。公式の応答例では、各メンバーが type id email name role added_at を持つ形です。

メンバーを検索・ロール変更・削除する

GET /v1/organizations/users は、追加された日時の新しい順にメンバーを返します。email パラメーターでメールアドレス検索ができ、大文字小文字を区別しません。jane+hiring@example.com のようなプラス記法も jane@example.com と同じアドレスとして一致します。roles パラメーターで、managed など特定のロールのメンバーだけに絞ることもできます。

curl "https://api.anthropic.com/v1/organizations/users?email=jane@example.com" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -H "anthropic-version: 2023-06-01"

メンバーの role は5種類の値のどれかです。

APIが割り当てられるのは user と managed の2つだけです。owner membership_admin primary_owner はclaude.aiの組織設定画面でのみ付与でき、これらを持つメンバーはAPI経由で変更も削除もできません。

POST /v1/organizations/users/{user_id} はロールを user か managed に更新します。管理系ロールのメンバーへの変更と、管理系ロールの割り当てはどちらも400です。

curl -X POST "https://api.anthropic.com/v1/organizations/users/user_01AbCdEfGhIjKlMnOpQrSt" \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"role": "managed"}'

DELETE /v1/organizations/users/{user_id} はメンバーを組織から削除し、購入済みシートを消費していればプールに返却します。成功すると type が user_deleted の小さなオブジェクトが返ります。

400が返ったら — 認証基盤の設定で切り分ける

メンバー系の操作は、組織のIDプロバイダー(IdP)がどこまで管理しているかで400になります。権限が足りないのではなく、IdP側が真実の情報源になっているための拒否です。スコープ不足なら400ではなく403が返ります。次の表で、自分の組織がどの操作を使えるかを先に判定できます。

実際の組織は複数の行に同時に当てはまることがあります。高度なSCIMでプロビジョニングしている組織なら、招待・ロール変更・削除のすべてが400になります。自動化の対象から外し、読み取りと監査に絞る使い方になります。

管理系ロールの拒否と合わせると、ロールとIdPに起因する400は次の4種類です。招待まわりやグループまわりの400は、それぞれの節で触れます。

• 管理系ロールが絡む: owner membership_admin primary_owner の変更・削除・割り当て
• IdPがロールを管理している: ロール変更が400
• IdPがメンバーシップを管理している: 削除が400
• IdPがユーザーを自動作成している: 招待作成が400

エラー本文の形はAdmin API共通の標準形式に従います。

招待を送信・取り消す

POST /v1/organizations/invites は招待メールを送信し、サーバー側で決まる expires_at を含む招待オブジェクトを返します。role には user か managed を指定します。

curl -X POST "https://api.anthropic.com/v1/organizations/invites" \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "email": "newhire@example.com",
    "role": "managed",
    "rbac_group_ids": ["rbac_group_01UvWxYzAbCdEfGhIjKlMn"]
  }'

応答の status は pending で始まり、受諾されると accepted、期限を過ぎると expired になります。招待は作成から21日で失効し、この期間は変更できません。失効日時は expires_at に入ります。APIリファレンスでは status の値として deleted も定義されていますが、意味の説明はありません。

取り消せるのは pending の招待だけです。accepted の招待を取り消すと400で、その場合は代わりにメンバーを削除します。expired の招待の取り消しも400です。メールアドレスやロールを変えたいときは、取り消してから作り直します。

400になる登録ミスも2つあります。同じメールアドレスへの保留中の招待が既にある場合と、そのアドレスが既にメンバーの場合で、どちらも既存リソースの名前がエラーに含まれます。

有限のシートプールから座席を割り当てるプランでは、保留中の招待もシートを1つ消費します。ティアを指定するパラメーターは無く、空きのある最も低いティアから自動で割り当てられます。空きが無ければ400で失敗し、自動購入はされません。シートは招待の取り消し・期限切れ・後からのメンバー削除のいずれでもプールに戻ります。

rbac_group_ids は最大100件まで指定でき、受諾された時点でそれらのグループに自動で割り当てられます。空でない値を渡すなら、write:members に加えて write:rbac_groups スコープも必要です。グループ割り当てはグループに紐づくロールの権限も同時に与えるため、別のスコープとして分離されています。

GET /v1/organizations/invites は pending accepted expired のすべてを新しい順に返します。ガイドは状態フィルターが無いと説明していますが、APIリファレンスには statuses と email のクエリパラメーターが載っていて、食い違っています。保留中だけが欲しいときは、statuses=pending を試したうえで、応答の status をクライアント側でも確かめると確実です。

グループとカスタムロール — Enterprise専用の範囲

グループはメンバーとカスタムロールを結びつける仕組みで、パスやスコープ名の rbac はロールベースアクセス制御(role-based access control)の略です。グループは単一の組織ではなく、親組織と配下の全組織を合わせたエンタープライズ全体が所有します。グループ系のスコープには、リンクされた全組織向けに作ったキーが必要です。

curl -X POST "https://api.anthropic.com/v1/organizations/rbac_groups" \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"name": "Engineering"}'

name は1〜255文字で、作成直後のグループにはロールもメンバーもありません。source_type は、claude.aiまたはAPIで作った direct と、IDプロバイダーから流し込まれた scim に分かれます。scim グループは読み取りだけで、名前変更・削除・メンバー変更はすべて400です。名前変更で変えられるのは name だけです。

グループへのメンバー追加は POST /v1/organizations/rbac_groups/{group_id}/members に user_id を渡します。対象がまだ組織に参加していなければ404、すでにグループにいれば400です。未参加者へは招待作成時の rbac_group_ids を使います。グループからの削除は、そのグループにいないユーザーだと404になります。

グループを削除しても、メンバーは組織に残ります。ただしグループに紐づいていたロールの権限を失い、グループ単位の支出上限があった場合はそれも効かなくなります。権限の棚卸しをしたうえで消す、という順序で運用すると事故を避けられます。

グループが持つロールは role_ids で返ります。ここに落とし穴が2つあります。

• ロールの一覧は組織単位、グループはエンタープライズ全体のため、別の組織に属するロールをIDで引くと404になる
• ロール情報が一時的に取れなかったとき、role_ids は空配列 [] ではなく null で返る。ロールを持たないグループと区別するには再試行する

roles(グループ側)と group_id(グループメンバー一覧の各要素)は非推奨のフィールドで、それぞれ role_ids と rbac_group_id と常に同じ値です。新しいコードでは後者を読みます。

カスタムロールは読み取り専用

GET /v1/organizations/rbac_roles と GET /v1/organizations/rbac_roles/{role_id}/permissions で、カスタムロールとその権限を参照できます。作成・編集はclaude.aiの組織設定画面でのみ行い、書き込みエンドポイントはありません。カスタムロールは組織単位のカタログで、組織レベルのキーで読めます。グループと違い、全組織向けのキーは要りません。

権限の action には、包括的な付与を表す値が2つあります。capability_access_all は全プロダクト機能、capability_access_all_ga はベータ・リサーチプレビューを除く全安定機能です。どちらも個別行には展開されず単独の1行で返ります。この包括行は、モデルへのアクセスや permission_ で始まる管理画面の権限は含みません。権限を集計するときは、包括行が他の行の機能名も丸ごと覆うものとして数えます。見落とすと過小評価になります。

権限一覧とグループメンバー一覧は、返す件数が limit に満たないのに has_more が true のことがあります。自分の組織で有効でない機能の行が省かれる、現在のメンバーだけが返る、という絞り込みが後から掛かるためです。件数ではなく has_more と next_page でループを終えてください。

ページネーションとレート制限の違い

メンバーと招待の一覧はID方式です。limit(既定20、最大1000)と、before_id か after_id のどちらか一方を渡します。レスポンスの first_id と last_id を使って has_more が false になるまで進めます。グループとカスタムロールの一覧は不透明なカーソル方式です。レスポンスの next_page をそのまま次の page パラメーターに渡し、next_page が null になるまで繰り返します。

同じAdmin API内で2方式が混在し、パラメーター名も終了条件も違います。ループは方式ごとに書き分けます。カーソル方式のループは次のようになります。

GROUP_ID="rbac_group_01UvWxYzAbCdEfGhIjKlMn"
page=""
while :; do
  res=$(curl -sG "https://api.anthropic.com/v1/organizations/rbac_groups/$GROUP_ID/members" \
    -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
    -H "anthropic-version: 2023-06-01" \
    --data-urlencode "limit=100" \
    ${page:+--data-urlencode "page=$page"})
  echo "$res" | jq -r '.data[].email'
  page=$(echo "$res" | jq -r '.next_page // empty')
  [ -z "$page" ] && break
done

レート制限は2系統です。

100回/分を共有するので、メンバーを1人ずつ GET する実装は、101人目で1分あたりの枠を超えます。email 検索で絞るか、一覧の limit を大きくして呼び出し回数を減らす方が安全です。招待だけは別枠なので、一括招待が他の読み取りを巻き込んで止めることはありません。

退職者のオフボーディングを組む

Adminキーが残る理由は、キーが個人ではなく組織に紐づくためです。作成者を削除しても、IdP経由でデプロビジョニングしても、作成者の権限を下げても、各キーは元のスコープのまま有効です。

数人規模のチームで自動化までは不要なら、Claudeチームのメンバー管理で扱っているUIからの招待・削除・ロール変更のほうが手早く済みます。

まとめ

自動化の可否は、スコープより先にIDプロバイダーの管理範囲で決まります。SCIMで組織を運用しているなら、書き込み系の多くは400になるので、読み取りと監査を軸に組み立てる形になります。ワークスペース単位の管理はClaude Admin APIでワークスペース管理を実装する、操作の証跡化はClaude Admin APIで監査ログは取れるかに続きます。