Claude Media
Claude Admin APIでワークスペース管理を実装する
AnthropicClaude Codeチュートリアル

Claude Admin APIでワークスペース管理を実装する

Admin APIでワークスペースを作成・一覧・アーカイブし、メンバーを追加するcurl実装例です。認証キーの種類や100件上限などのつまずきもまとめます。

読了目安 約17分

Admin APIでワークスペースを操作するには、組織全体を管理できるキーが必要です。ワークスペース専用のAPIキーでは呼び出せず、Admin APIキーかorg:admin権限のOAuthトークン、あるいは特定のワークスペースに紐づいていない個人・サービスアカウントキーのいずれかを使います。この記事では、ワークスペースの作成・一覧取得・メンバー追加・アーカイブをcurlで実装する手順と、実装時に踏みやすいつまずきをまとめます。

Admin APIでワークスペースを操作する前提

ワークスペースはAPIキーの利用を環境やチーム単位で分離するための箱です。組織には必ず「Default Workspace」が1つ存在し、これは名前変更もアーカイブも削除もできません。追加のワークスペースは組織あたり最大100件まで(アーカイブ済みは数に含まれない)作成でき、それを超える場合はアカウントチームへの申請が必要です。

ワークスペース自体の作成・更新・アーカイブと組織メンバーの管理は、すべて組織レベルの操作としてAdmin APIが担います。個々のワークスペース内のリソース(Files APIのファイル、Batch APIのバッチ、Skills APIのスキル)はワークスペースにスコープされますが、ワークスペースという箱そのものを作る操作は一段上の権限が要ります。

認証で必ず確認することは、使うキーがワークスペースに固定されていないかです。単一ワークスペースに紐づく個人キーやサービスアカウントキーではAdmin APIのエンドポイントは呼び出せません。複数ワークスペースにまたがる権限を持つキー、Admin APIキー、org:adminトークンのいずれかを用意してから実装に入ります。

ワークスペースを作成する

POST /v1/organizations/workspacesにワークスペース名を渡すだけで作成できます。

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

レスポンスにはワークスペースID(wrkspc_で始まる文字列)が含まれます。このIDは後続のメンバー追加・アーカイブ操作すべてで使うので、作成直後に控えておく必要があります。名前だけでなく色分けもConsole側では設定できますが、Admin API経由の作成では名前の指定のみです。

ワークスペースを一覧取得する

GET /v1/organizations/workspacesでアーカイブ済みを含めるかどうかを指定して一覧できます。

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

ここで注意が必要なのが、この一覧にDefault Workspaceは出てこないことです。APIキーやレスポンスヘッダーにはwrkspc_形式のIDが付きますが、List Workspacesの結果には含まれません。Default Workspaceに紐づくAPIキーや利用状況レポートはworkspace_idがnullとして表示されるため、複数ワークスペースにまたがるキーのnullと見分けがつきません。判別にはAPIキーのscopeフィールドを見ます。単一ワークスペースに紐づくキーであれば実IDが入り、それが無い場合は複数ワークスペースキーだと分かります。

メンバーを追加する

ワークスペースへのメンバー追加は組織メンバーのユーザーIDとロールを指定して行います。

curl -X POST "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/members" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "user_id": "user_01XyDMpzjS89pFZXqSFUBDr6",
    "workspace_role": "workspace_developer"
  }'

割り当てられるロールはworkspace_admin / workspace_developer / workspace_limited_developer / workspace_userの4つです。課金情報を見られるworkspace_billingロールは組織のbillingロールから自動的に継承される仕組みで、Admin API経由でも手動で割り当てることはできません。組織admin・billingメンバーはそもそも全ワークスペースへの権限を自動で持つため、Admin APIでの追加操作は組織のuser・developerロールのメンバーに対して行うのが基本になります。

ワークスペースをアーカイブする

不要になったワークスペースはアーカイブで無効化します。削除ではなく、履歴を残したまま利用停止する操作です。

curl -X POST "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

アーカイブは取り消せません。実行すると、そのワークスペースに紐づく全APIキーが数秒以内にアーカイブ状態になり、複数ワークスペースキーもそのワークスペースへはアクセスできなくなります。Claude Codeワークスペースをアーカイブすると、Console課金経由でのClaude Codeサインイン自体が組織全体で止まるため、実装前に対象ワークスペースの用途を必ず確認してください。

実装で使い分ける3つの構成パターン

Admin APIでワークスペースを分ける目的は、公式ドキュメントの用途分類に沿うと次の3パターンに整理できます。

構成分ける単位効果
環境分離分ける単位development / staging / production効果レート制限を段階的に緩め、本番トラフィックだけ完全な制限で運用できる
チーム・部門分離分ける単位エンジニアリング / データサイエンス / サポート効果チームごとに支出上限とアクセス範囲を独立管理できる
プロジェクト単位分ける単位製品・案件ごと効果利用状況・コストをプロジェクト単位で追跡できる

いずれのパターンでも、ワークスペースの作成・メンバー管理はAdmin APIで自動化できますが、レート制限と支出上限の設定自体はConsoleのワークスペース設定画面が窓口です。Admin APIにはワークスペースを作る・メンバーを増減させるエンドポイントはあっても、限度額を書き込むエンドポイントは用意されていません。読み取りはRate Limits APIで可能なので、自動化パイプラインを組む場合は「作成はAdmin API、限度額設定はConsoleでの手動確認」という役割分担になります。

よくあるつまずき

  • ワークスペーススコープのキーでAdmin APIを叩いてエラーになる: 単一ワークスペースに紐づく個人キー・サービスアカウントキーは拒否されます。Admin APIキーか、ワークスペースを指定しない個人・サービスアカウントキーを使う必要があります
  • Default WorkspaceのIDが一覧に出ないため見失う: anthropic-workspace-idレスポンスヘッダーやGet Workspaceエンドポイントで個別に取得します。名前は"Default"で返ります
  • アーカイブ後に元に戻そうとしてできない: アーカイブは不可逆です。一時停止ではなく恒久的な無効化として扱う必要があります
  • メンバー追加でworkspace_billingロールを指定してエラーになる: このロールは組織のbillingロールから自動継承される専用ロールで、Admin API経由でも手動割り当てはできません
  • 組織adminのロールをワークスペース単位で変更しようとして失敗する: 組織adminは全ワークスペースへの権限を自動継承しているため、その権限を組織roleの変更なしにワークスペース単位で外すことはできません

レスポンスヘッダーからワークスペースを特定する

Admin APIでの管理とは別に、実運用では「このAPIリクエストはどのワークスペースで処理されたか」を後から突き止めたい場面が出てきます。Claude APIのレスポンスにはanthropic-workspace-idヘッダーが必ず付き、そのリクエストで使われたAPIキーやアクセストークンが解決したワークスペースのIDが入ります。Default Workspaceで処理された場合も同様にIDが返るため、ヘッダーの有無ではなくID自体を見て判定します。このヘッダーは、認証が完了する前に失敗したリクエスト(401エラーなど)や、そもそもワークスペースに解決されないAdmin APIリクエストでは付きません。

curl -sS -D - -o /dev/null https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }' | grep -i '^anthropic-workspace-id'

取得したワークスペースIDは、Usage and Cost APIのレポートやAdmin API上のAPIキーオブジェクトのworkspace_idと突き合わせて、そのリクエストがどの利用状況・コストレポートに計上されたかを確認するのに使えます。Get WorkspaceエンドポイントにこのIDを渡せば、Default Workspaceかどうかも"name": "Default"という応答で判別できます。Claude Managed AgentsのセッションAPIなど、Messages API以外のエンドポイントでも同じヘッダーが返るため、セッション作成時にどのワークスペースに紐づいたかを記録しておく用途にも使えます。

ワークスペースにスコープされるリソースの範囲

ワークスペースという箱の中で、実際にどのリソースが分離されるかを把握しておくと設計を誤りません。Files APIで作成したファイル、Batch APIで作成したメッセージバッチ、Skills APIで作成したスキルは、いずれもワークスペース単位でスコープされます。単一ワークスペースキーで作ったファイルは、別のワークスペースキーからは見えません。

一方で、すべてのリソースがこの原則に従うわけではありません。MCP tunnelsはワークスペース内で作成されますが、管理自体はWorkload Identity Federation経由のworkspace:manage_tunnelsトークンで行い、通常のAPIキーではありません。同時接続数10本という上限は組織全体で共有され、ワークスペースごとに10本ずつ確保されるわけではない点に注意が必要です。プロンプトキャッシュもAPI・AWS・Microsoft Foundryでは同様にワークスペース単位で分離されますが、Amazon BedrockとGoogle Cloudでは組織単位での分離になるため、マルチクラウドでワークスペース設計を横展開する場合はこの違いを踏まえる必要があります。

Claude Codeワークスペースは自動作成される特別枠

Admin APIで作るワークスペースとは別に、組織メンバーが初めてConsoleアカウントでClaude Codeにサインインすると、Anthropicが自動的に「Claude Code」という名前のワークスペースを作成し、そのメンバーを追加します。このワークスペース内のAPIキーはサインイン時にAnthropic側が発行するため、Consoleから手動でキーを作ることはできません。キーの持ち主がワークスペースまたは組織から外れると、そのキーは即座に使えなくなります。通常のワークスペースキーが持ち主に関係なく動き続けるのとは対照的な挙動です。Claude Codeの利用量を組織の他のAPIワークロードから独立して管理したい場合、このワークスペースの存在を前提に設計する必要があります。

まとめ

Admin APIでのワークスペース管理は、作成・一覧取得・メンバー追加・アーカイブの4操作が中心です。呼び出しにはAdmin APIキーかorg:adminトークン、あるいはワークスペース非スコープの個人・サービスアカウントキーが必須で、通常の開発用キーでは弾かれます。レート制限や支出上限といった限度額の設定はConsole側の役割で、Admin APIの守備範囲には含まれません。環境分離・チーム分離・プロジェクト単位のいずれで設計する場合も、Claude Codeワークスペースが自動作成される特別枠であることを踏まえておくと、後から「なぜこのワークスペースだけキーの挙動が違うのか」で詰まらずに済みます。組織全体の契約形態から設計したい場合はClaude法人プランの契約ガイド、Enterpriseプランの機能構成はClaude Enterpriseとはで扱っています。コンプライアンス要件でワークスペース単位のデータ保持を切り替えたい場合の契約範囲はClaude Zero Data Retentionが有効になる契約形態の切り分けを参照してください。

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

関連する記事

Anthropic をもっと見る →