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

Admin APIでワークスペースを操作するには、組織全体を管理できるキーが必要です。ワークスペース専用のAPIキーでは呼び出せません。この記事では、ワークスペースの作成・一覧取得・メンバー追加・アーカイブをcurlで実装する手順と、公式ページ同士で記述が分かれる箇所を扱います(操作の履歴はAdmin APIの監査ログ取得で追跡できます)。

呼び出す前に確認すること

ワークスペースは、APIキーの利用を環境やチーム単位で分ける箱です。組織には必ず「Default Workspace」が1つあり、名前変更・アーカイブ・削除はできません。追加できるのは組織あたり最大100件で、アーカイブ済みは数に含まれません。上限を超える場合は、アカウントチームへの相談が必要です。

最初に引っかかるのは認証です。Admin APIが受け付けるのは3種類で、ワークスペースに固定されたキーは通りません。

キーの種類に加えて、組織の種類でも使えるエンドポイントが変わります。

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

POST /v1/organizations/workspacesにワークスペース名を渡すと作成できます。名前は1〜40字です。

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", "display_color": "#2F7D5B"}'

レスポンスにはワークスペースID(wrkspc_で始まる文字列)が入ります。メンバー追加とアーカイブはこのIDで呼ぶので、作成直後に控えておきます。

名前以外に指定できる項目は4つあります。display_colorはConsole上の識別色、tagsは文字列のキーと値の組です。書式の制約は後半の「作成リクエストが通らないとき」にまとめました。

data_residencyはデータの保存地域と推論地域の設定です。保存地域のworkspace_geoは作成後に変更できません。省略するとworkspace_geoは"us"、許可する推論地域は"unrestricted"、既定の推論地域は"global"になります。

external_key_idは顧客管理の暗号化キー(CMEK)の設定IDです。一度付けると、外すことも差し替えることもできません。

一覧にDefault Workspaceが出ないとき

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

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

素のまま呼ぶと、Default Workspaceは一覧に入りません。Workspacesのページでは、include_default=trueを付けたときだけ一覧に入るとされています。一方、List Workspacesのリファレンスのクエリ表にはafter_id / before_id / include_archived / limitの4つしか載っていません。自動化に組み込む前に、返り値で一度確かめると安全です。

Default Workspaceに紐づくAPIキーや利用状況レポートでは、workspace_idがnullになります。複数のワークスペースにまたがるキーもnullなので、この値だけでは区別できません。判別にはAPIキーのscopeフィールドを使います。単一ワークスペースのキーなら、Default Workspaceに固定されたキーも含めて実IDが入ります。

メンバーを追加する

追加には、User Management APIで一覧取得できる組織メンバーのユーザー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_restricted_developer / workspace_userの4つです。Workspacesのページの役割表にはWorkspace Limited Developerがありますが、リファレンスのenumに入っているのはworkspace_restricted_developerだけです。workspace_limited_developerと書くとenumの値と一致しません。課金情報を見るworkspace_billingは、組織のbillingロールから自動で継承されるロールで、追加の際に指定できません。

組織側のロールは招待の手順で決めます。組織adminとbillingは全ワークスペースへ自動で入るため、追加が必要なのは組織のuserとdeveloperです。自動で入ったadminとbillingは、そのロールを持つ間はワークスペースのロール変更も削除もできません。例外はbillingからWorkspace Adminへの引き上げだけで、それ以外は組織のロールを先に変えます。Default Workspaceにはメンバー一覧がなく、アクセスは各メンバーの組織ロールに従います。メンバーを足す先にはなりません。

レート制限はAPIで読め、設定はConsoleで行う

レート制限はConsoleのRate limitsページで、Workspaceドロップダウンから対象を選んでモデルごとに設定します。支出上限は、Settings > Workspacesで対象のワークスペースを開き、パネルのSpend limitsで決めます。ヘルプ記事では、どちらも1つの「Limits」タブにまとめて説明しています。ワークスペースの限度額は、組織の限度額を超えて設定できません。未設定なら組織の限度額と同じ値になります。Default Workspaceには、限度額を設定できません。

API側で読めるのはレート制限です。支出上限のAPI(Spend Limits API)はClaude Enterprise専用で、Consoleの組織では使えません。ワークスペースごとのレート制限は、次のエンドポイントで読みます。

curl "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/rate_limits?include_inherited=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

include_inheritedを付けないと、ワークスペース側で上書きした項目だけが返ります。trueにすると、組織から引き継いでいる値も項目ごとに並び、各値のsourceで上書きか継承かが分かります。プロビジョニングの自動化が作ったワークスペースの設定を、Consoleで入れた値と突き合わせる用途に向きます。

Default Workspaceは上書きを持てないので、このエンドポイントに項目が出ません。その値は組織向けのGET /v1/organizations/rate_limitsで読みます。

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

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

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キーが数秒以内にアーカイブ状態になり、Admin APIの一覧にはアーカイブ済みとして残ります。複数ワークスペースキーも、そのワークスペースでは動かなくなります。アーカイブ済みは100件の上限に数えられないため、枠を空ける手段にもなります。

Claude Codeワークスペースをアーカイブすると、Console課金経由でのClaude Codeサインインが組織全体で止まります。対象の用途を確かめてから実行します。

ワークスペースを分ける単位

分け方は、公式の用途例に沿うと環境(development / staging / production)、チームや部門、プロジェクトの3通りです。どれを選んでも、限度額は組織の限度額の内側に収まります。

環境で分けるなら、本番だけ組織の限度額いっぱいにし、開発側を低く絞れます。チームで分けるなら、支出上限とアクセス範囲をチーム単位で持てます。プロジェクトで分けると、利用状況とコストを案件ごとに追えます。

作成リクエストが通らないとき

作成時の項目には、リファレンスで次の制約が定められています。

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

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-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を渡し、"name": "Default"が返ればDefault Workspaceです。Claude Managed Agentsのセッション作成のレスポンスにも同じヘッダーが付くので、セッションがどのワークスペースに属するかの記録にも使えます。

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

Files APIのファイル、Batch APIのメッセージバッチ、Skills APIのスキルは、ワークスペース単位でスコープされます。単一ワークスペースキーで作ったファイルは、別のワークスペースのキーからは見えません。

すべてのリソースが同じ扱いではありません。MCP tunnelsはワークスペース内で作られますが、管理にはWorkload Identity Federationで得るworkspace:manage_tunnelsトークンを使い、APIキーは使いません。同時に有効にできる10本という上限は組織全体で共有されます。プロンプトキャッシュは、Claude API・Claude Platform on AWS・Microsoft Foundryではワークスペース単位で分かれ、Amazon BedrockとGoogle Cloudでは組織単位です。複数のクラウドで同じワークスペース設計を使い回すときは、この差に注意が要ります。

キーの持ち主を外したときの挙動も、キーの種類で分かれます。個人キーとサービスアカウントキーは、持ち主がそのワークスペースから外れると、まもなく使えなくなります。サービスアカウントキーは、作った人が外れても動き続けます。ワークスペースキーも動き続けます。個人キーは、ユーザーが組織から外れた時点でアーカイブされ、再招待しても復元されません。

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

組織メンバーが初めてConsoleアカウントでClaude Codeにサインインすると、「Claude Code」という名前のワークスペースが自動で作られ、そのメンバーが追加されます。以降にサインインするメンバーも同じように追加されます。このワークスペースのキーはサインイン時に発行されるので、Consoleから手で作ることはできません。

通常のワークスペースキーとの違いは3点です。キーの持ち主がワークスペースか組織から外れると、そのキーは使えなくなります。Claude Codeの利用はレート制限が別枠で、管理者はConsoleのRate limitsページで、組織の制限に対するこの枠の割合を絞れます。メンバーごとの月間支出上限を設定できるのも、このワークスペースだけです。

まとめ

作成時にしか決められないworkspace_geoとexternal_key_id、取り消せないアーカイブは、後から戻せない3点です。自動化に組み込む前に値と運用を決めておくと、やり直しが利かない部分で迷わずに済みます。組織全体の契約形態から設計するならClaude法人プランの契約ガイド、Enterpriseプランの機能構成はClaude Enterpriseとはが出発点です。ワークスペース単位でデータ保持を切り替える契約の範囲は、Claude Zero Data Retentionが有効になる契約形態の切り分けで扱っています。