Claude User Management APIでメンバー管理を実装する
Claude Enterprise組織のメンバー・招待・グループ・カスタムロールをAdmin APIで操作する実装をcurlで解説します。
User Management APIで何が操作できるか
User Management APIは、Claude Enterprise(claude.ai)組織の人とグループをプログラムから操作するためのAPIです。メンバーの一覧・ロール変更・削除、招待の送信・取り消し、グループの作成とメンバー管理、カスタムロールの参照までをカバーします。
User Management APIとは、Admin APIのうち /v1/organizations/users /v1/organizations/invites /v1/organizations/rbac_groups /v1/organizations/rbac_roles 系のエンドポイントを指す呼び名です。独立した別のAPIではなく、Admin APIキーで到達する同じエンドポイント群の一部にあたります。メンバー・招待のエンドポイントはClaude Console(Claude Platform)組織とClaude Enterprise組織の両方で使えますが、グループとカスタムロールの読み取りはClaude Enterprise組織限定です。
ベータヘッダーは実質不要な点が実装上のポイントです。グループとカスタムロールのエンドポイントは anthropic-beta: ce-user-management-2026-07-13 ヘッダーを付けなくても動作します。ヘッダーを付けたリクエストも受理され、挙動は変わりません。
事前準備 — 必要なスコープ
呼び出すエンドポイントによって必要なスコープが変わります。メンバー・招待のGETと全カスタムロールエンドポイントには read:members、メンバー・招待のPOST/DELETEには write:members、グループのGETには read:rbac_groups、グループのPOST/DELETEには write:rbac_groups が必要です。read:org_audit スコープを持つキーは、このページの全GETエンドポイントとCompliance APIの読み取りエンドポイントの両方を呼べます。
キーの作成手順とスコープの選び方はClaude Admin APIキーの取得方法とスコープ選択にまとめています。すべてのリクエストで x-api-key ヘッダーと anthropic-version ヘッダーが必須です。
メンバーを一覧・検索する
GET /v1/organizations/users は組織のメンバーを、追加された日時の新しい順に返します。email パラメーターでメールアドレス検索もでき、大文字小文字を区別せず jane+hiring@example.com のようなプラス記法も同じアドレスとして扱います。
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種類の値のいずれかです。
| ロール | 意味 |
|---|---|
user | 意味標準メンバー |
managed | 意味グループに紐づくカスタムロールで権限が決まるメンバー |
owner | 意味組織オーナー |
membership_admin | 意味メンバー管理権限を持つメンバー |
primary_owner | 意味組織のプライマリオーナー(必ず1人) |
APIが割り当てられるのは user と managed の2つだけです。owner membership_admin primary_owner の管理系ロールはclaude.aiの組織設定画面でのみ付与でき、これらのロールを持つメンバーはAPI経由で変更・削除できません。
メンバーのロールを変更・削除する
POST /v1/organizations/users/{user_id} はロールを user か managed に更新します。管理系ロールを持つメンバーへの変更は400エラーになり、管理系ロール自体を割り当てることもできません。組織の認証基盤が高度なSSOや高度なSCIMプロビジョニングでロールを管理している場合、この更新自体が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} はメンバーを組織から削除し、購入済みシートを消費していればプールに返却します。管理系ロールのメンバーはこのエンドポイントでは削除できず、SCIMがメンバーシップを管理している組織では削除自体が400になります。
招待を送信・取り消す
POST /v1/organizations/invites は招待メールを送信し、サーバー側で設定された expires_at を含む招待オブジェクトを返します。role には user か managed を指定します。すでに同じメールアドレスへの保留中招待があるか、そのアドレスが既にメンバーの場合は400が返り、既存リソースの名前がエラーに含まれます。
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"]
}'有限のシートプールから座席を割り当てるプランでは、招待の作成が自動的に空きのある最も低いティアからシートを消費します。ティアを指定するパラメーターは無く、空きが無ければ400で失敗します(自動購入はされません)。招待は pending → accepted または expired と状態が遷移し、取り消せるのは pending の招待だけです。メールアドレスやロールを変更したい場合は取り消してから新規作成し直します。
rbac_group_ids を指定すると、招待が承諾された時点でそのグループへ自動的に割り当てられます。このフィールドを空でない値で渡す場合、write:members に加えて write:rbac_groups スコープも必要です。
グループを操作する
グループはメンバーとカスタムロールを結びつける仕組みで、エンドポイントパスとスコープ名の 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"}'各グループには source_type があり、claude.aiで直接作成された direct と、IDプロバイダーからプロビジョニングされた scim を区別します。scim グループは読み取りだけ可能で、名前変更・削除・メンバー変更はすべて400になります(IDプロバイダー側が真実の情報源のため)。グループにメンバーを追加するには POST /v1/organizations/rbac_groups/{group_id}/members を使いますが、対象ユーザーがまだ組織に参加していない場合は404になるため、未参加者へのグループ割り当ては招待作成時の rbac_group_ids を使います。
カスタムロールは読み取り専用
GET /v1/organizations/rbac_roles と GET /v1/organizations/rbac_roles/{role_id}/permissions で、組織のカスタムロールとその権限を参照できます。カスタムロール自体の作成・編集はclaude.aiの組織設定画面でのみ行い、APIには書き込みエンドポイントがありません。
権限の action には capability_access_all(全プロダクト機能への包括的な付与)や capability_access_all_ga(ベータ・リサーチプレビューを除く全安定機能への付与)という特別な値があり、これらは個別行に展開されず単独の行として返ります。ロールが実際に何を許可しているかを集計する際は、この包括行を見落とすと過小評価します。
ページネーションとレート制限の実装上の違い
メンバーと招待の一覧はID方式のページネーションです。limit(既定20、最大1000)と、before_id か after_id のどちらか一方を渡し、レスポンスの first_id / last_id を使って has_more が false になるまでページを送ります。対してグループとカスタムロールの一覧は不透明なカーソル方式です。レスポンスの next_page 値をそのまま次のリクエストの page パラメーターに渡し、next_page が null になるまで繰り返します。同じAdmin API内でも一覧の実装方式が2種類あるため、片方のページネーション実装をもう片方に流用すると動きません。
Admin APIのエンドポイントは組織単位で1分あたり100リクエストのレート制限がかかります。ただし招待作成だけは別枠で、1時間あたり1,200リクエストです。大量のメンバーを一括処理するスクリプトを書く場合、この上限を超えないよう間隔を空ける実装にしておく必要があります。
anthropic-versionヘッダーは省略できない
このページのすべてのエンドポイントで anthropic-version ヘッダーが必須です。省略するとリクエストは失敗します。利用できるバージョン文字列は随時追加されるため、固定の値をハードコードするより、契約しているSDKのバージョンに対応した値を都度確認しておくほうが安全です。エラーレスポンスの形式は他のAdmin APIエンドポイントと共通で、標準のエラー形式に従います。
よくあるつまずき
- オーナーやメンバー管理者のロールをAPIで付与しようとして400になる: APIが割り当てられるのは
userとmanagedだけです。管理系ロールはclaude.aiの組織設定画面でのみ操作します - SCIM連携している組織で招待作成が400になる: IDプロバイダーが自動的にユーザーをプロビジョニングしている(JITまたはSCIM)組織では、招待作成そのものがAPI経由でできません
- グループのメンバー追加が失敗する: グループ系スコープはリンクされた全組織向けのキーが必要です。単一組織スコープのキーでは足りません
rbac_group_idsを空でない値で渡したのに400:write:rbac_groupsスコープが無いキーで指定すると失敗します。グループ割り当てはそのグループが持つロールの権限も同時に付与する操作なので、別スコープとして分離されています
退職者オフボーディングの実装例
GET /v1/organizations/users?email=でメールアドレスからメンバーを検索しuser_idを取得するDELETE /v1/organizations/users/{user_id}で削除する。保有していたシートはプールに返却される- 検索してメンバーが見つからない場合は、まだ招待段階の可能性があるため招待一覧から該当の
pending招待を探して取り消す
Admin APIキー自体は作成者が組織を離れても失効しません。作成者をオフボーディングする際は、claude.aiの組織設定「API」セクションでそのメンバーが作成したキーを個別に削除し、必要なら別のメンバーで作り直します。数人規模のチームで自動化までは不要な場合は、Claudeチームのメンバー管理で扱っているConsole UIからの招待・削除・ロール変更のほうが手早く済みます。
まとめ
User Management APIは、Admin APIのうちメンバー・招待・グループ・カスタムロールを扱うエンドポイント群の呼び名で、Claude Enterprise組織向けにグループとカスタムロールの読み取りが追加されています。管理系ロールの操作やカスタムロールの編集はAPIの範囲外で、claude.aiの組織設定画面が担います。オフボーディングやグループ監査のような定型業務を自動化したい場合に、メンバー・招待・グループの3系統を組み合わせて使うAPIです。ワークスペース単位の管理はClaude Admin APIでワークスペース管理を実装する、操作の証跡化はClaude Admin APIで監査ログは取れるかを参照してください。