ホーム / チュートリアル / Admin API で組織メンバーとワークスペースを管理する

Admin API で組織メンバーとワークスペースを管理する

Claude API プロフェッショナル 8分で読めます

Anthropic の Admin API は、組織のメンバー・招待・ワークスペース・API キーを、Claude Console の画面操作ではなくプログラムから管理するための API です。入退社のオンボーディングとオフボーディングの自動化、ワークスペースのアクセス管理、API キーの棚卸しといった用途が想定されています。

本記事は Anthropic の公式ドキュメント「Admin API」に基づく非公式の日本語解説です。実際に叩く前に、この API は個人アカウントでは利用できないという前提と、認証情報が3種類あってできることが違うという点を押さえておくと迷いません。

Admin API とは何か

Admin API が扱う対象は、モデルの推論ではなく組織そのものです。公式ドキュメントは管理できる資源として次を挙げています。

典型的な用途として公式が挙げているのは、オンボーディングとオフボーディングの自動化、ワークスペースのアクセス管理、API キーの監査の3つです。人事システムやディレクトリと連携させて、入社時に招待を送り、退職時にメンバーを外す、という流れを人手を介さずに回すのが素直な使い方になります。

最初に確認する2つの前提

1つ目。個人アカウントでは使えません。 公式ドキュメントは冒頭で「Admin API は個人アカウントでは利用できない」と明記しています。チームで使うには Console の Settings → Organization で組織を作るところから始まります。ここを飛ばして API を叩いても、そもそも対象になる組織がありません。

2つ目。契約形態によって使えるエンドポイントが違います。 これは見落としやすい部分なので、先に整理しておきます。

「ドキュメントに書いてあるのに動かない」の多くは、この2つの前提のどちらかに当たっています。叩く前に自分の契約形態を確認してください。

3つの認証情報と権限

Admin API は3種類の認証情報を受け付けます。どれでもよいわけではなく、使える範囲が違います。

受け付ける3つの認証情報

ここが実務上の分かれ目です。 公式ドキュメントは「Admin API キーはほとんどのエンドポイントを覆う」としたうえで、サービスアカウント、フェデレーション発行者、フェデレーションルールのエンドポイントは org:admin の OAuth トークンしか受け付けないと書いています。つまり Workload Identity Federation 周りを API から管理したいなら、Admin API キーでは足りません。

OAuth ベアラトークンを用意する

ant CLI で org:admin スコープのプロファイルにログインし、トークンを環境変数へ出します。

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

--profile admin は org:admin の資格情報を専用プロファイルに保存し、そのプロファイルを CLI のアクティブなものにします。公式ドキュメントは運用上の注意を3つ挙げています。 管理作業専用のシェルを使うこと、作業が終わったら環境変数を解除すること、そして ant profile activate default で CLI を元のプロファイルへ戻すことです。エクスポートした変数はそのシェルの全ての SDK と CLI の呼び出しに効くので、普段の開発シェルでこれをやると、意図しない呼び出しまで管理者権限で走ります。

対話的に取得したトークンは短命です。 リクエストが 401 を返し始めたら、export の行を再実行して取り直します。また、SDK と ant CLI は ANTHROPIC_AUTH_TOKEN を自動で読むので、同じシェルでは ANTHROPIC_API_KEY を未設定にしておきます。両方あるとどちらが送られるかで挙動が変わります。

CI などの非対話のワークロードは、この対話ログインを行いません。Workload Identity Federation で認証し、SDK と CLI がフェデレーション用の環境変数からトークン交換を行います。

組織情報を取得して疎通を確かめる

最初の1本は /v1/organizations/me が確実です。認証情報が通っているかだけを確認できます。

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

Admin 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"

返るのは次の形です。

{
  "id": "12345678-1234-5678-1234-567812345678",
  "type": "organization",
  "name": "Organization Name"
}

SDK からも同じことができます。Python / TypeScript / C# / Go / Java / PHP / Ruby の各 SDK は Admin API を client.beta.organization の下に、ant CLI は ant beta:organization の下に公開しています。

const client = new Anthropic();

const organization = await client.beta.organization.retrieve();

console.log(`id: ${organization.id}`);
console.log(`name: ${organization.name}`);

組織のロールと権限

組織レベルのロールは5つです。

ロール権限
userプレイグラウンドを使える
claude_code_userプレイグラウンドと Claude Code を使える
developerプレイグラウンドを使え、API キーを管理できる
billingプレイグラウンドを使え、請求情報を管理できる
admin上記すべてに加えて、ユーザーを管理できる

組織の owner と primary owner は admin の権限をすべて持ち、さらにadmin を管理できます。公式ドキュメントのこのページで「admin ロール」と書かれている箇所は、owner と primary owner にも当てはまります。

組織メンバーと招待を扱う

組織メンバーの一覧取得、ロールの更新、削除ができます。

メンバーを一覧する

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

CLI と SDK では次のようになります。

ant beta:organization:users list --limit 10
client = anthropic.Anthropic()

users = client.beta.organization.users.list(limit=10)

# 必要に応じて次のページを自動で取得する
for user in users:
    print(f"{user.id}: {user.email} ({user.role})")

limit の意味を取り違えないでください。 公式ドキュメントは明示しています。Python / TypeScript / C# / Go / Java の SDK の list メソッドはイテレータを返し、必要に応じて次のページを取りに行くため、limit は1ページあたりの件数であって取得総数ではありません。一方 PHP / Ruby / curl の例は1ページだけを返します。CLI の --limit は、メンバー・招待・ワークスペース・ワークスペースメンバー・API キーの各一覧で結果件数の上限として働きます。同じ名前の引数が実装によって別の意味を持つので、件数の想定でロジックを書くときは注意が要ります。

メンバーのロールを更新する

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"}'
ant beta:organization:users update \
  --user-id user_01XyDMpzjS89pFZXqSFUBDr6 \
  --role developer

ただし admin ロールのメンバーは API から削除できません。 公式の FAQ が明確に「API は admin ロールを持つメンバーを削除できない」としています。オフボーディングの自動化を組むときは、admin の除去だけは Console での手作業が残る前提で設計してください。ここを自動化の対象に含めてしまうと、退職処理のスクリプトが admin のところで必ず失敗します。

招待の有効期限

組織の招待は21日で失効します。公式 FAQ によれば、この期間は設定で変更できません。招待を送りっぱなしにすると失効した招待が溜まっていくので、定期的な棚卸しの対象に入れておきます。

ワークスペースとAPIキーを扱う

ワークスペースとそのメンバー

ワークスペースは、組織の中で利用と権限を区切るための単位です。Admin API では作成・取得・一覧・更新・アーカイブと、ワークスペースメンバーの管理ができます。前述のとおり Claude Platform on AWS では、Admin API のうちこのワークスペース系と外部キー系だけが使えます。

API キーは「作れない」

ここが Admin API でいちばん誤解されやすい点です。 公式 FAQ は次のように書いています。「いいえ。API キーは Claude Console で作成します。Admin API は既存のキーの読み取り、名前の変更、状態の変更しかできません」。

つまり Admin API はキーの発行機ではなく、棚卸しと停止のための道具です。「キー発行まで含めた完全な自動化」を前提に設計すると途中で行き詰まります。逆に、不要になったキーを機械的に見つけて無効化するという用途にはそのまま使えます。

メンバーを削除したとき、キーはどうなるか

これはオフボーディングの設計に直結します。公式 FAQ の記述はキーの種類ごとに違います。

この非対称性が事故のもとになります。 退職者のアカウントを消せば、その人が関わったキーはすべて止まる、と考えるのは誤りです。サービスアカウントキーとワークスペース API キーは残ります。逆に、本番のバッチを個人キーで動かしていた場合は、その人が組織を離れた瞬間に本番が止まります。自動化を書く前に、自組織のキーがどの種類なのかを一度洗い出しておくと、この両方向の失敗を避けられます。

使用量・コスト・レート制限・監査

Admin API のページからは、隣接する4つの API も参照されています。用途で使い分けます。

運用上の注意点とFAQ

公式が挙げるベストプラクティス

どれも当たり前に見えますが、Admin API はこれらを機械で回すために存在します。人手の運用で守りきれなかった項目こそ、この API で自動化する価値があります。とくに「意味のある名前を付ける」は、後から棚卸しをするときに効いてきます。名前が test や key1 ばかりのキーは、一覧が取れても止めてよいかを判断できません。

FAQ の要点

Admin API を使うのに必要な権限は。 Admin API キー（sk-ant-admin で始まる）、org:admin スコープの OAuth ベアラトークン、または特定のワークスペースにスコープされていない個人キーかサービスアカウントキーのいずれかです。Admin API キーを発行できるのは admin ロールのメンバーだけ、org:admin トークンを取得できるのは admin / owner / primary owner だけです。個人キーとサービスアカウントキーの権限は、紐付いたアカウントと同じになります。

Admin API で新しい API キーを作れるか。 作れません。作成は Claude Console で行い、Admin API は既存キーの読み取り・改名・状態変更のみです。

ユーザーを削除したとき API キーはどうなるか。 キーの種類によって挙動が異なります（前節の一覧を参照）。

組織の admin を API から削除できるか。 できません。

組織の招待はどのくらい持つか。 21日で失効し、この期間は設定変更できません。

実装に入る前のチェックリスト

ここまでを踏まえると、Admin API を組み込む前に確かめておくことは4点に整理できます。

各エンドポイントのパラメータとレスポンスの詳細は、公式の Admin API リファレンスに揃っています。本記事はその全体像と、実装前に知っておくと手戻りが減る前提条件をまとめたものです。

本記事は Anthropic の公式ドキュメント「Admin API」に基づく非公式の日本語解説です。仕様は変更される場合があります。最新の内容は公式ドキュメントをご確認ください。

関連チュートリアル / 次に読む

Usage and Cost API で組織の使用量とコストを追う Workload Identity Federation で API キーを配らずに認証する Claude Code の設定と権限 Claude APIのレート制限 コストを効果的に管理する
← チュートリアル一覧へ戻る カテゴリで探す