Claude Workspacesのロール継承とAPIキーのスコープ

Claude Workspacesは何のための仕組みか

組織のAPI利用が増えると、開発・ステージング・本番のトラフィックが1本の請求と1組のレート制限に混ざり込みます。どのプロジェクトがいくら使っているかも分からなくなります。Workspacesは、APIキー・メンバー・リソース上限をプロジェクトや環境ごとに分離しつつ、請求と管理は組織レベルに一本化する仕組みです。

すべての組織に「Default Workspace」が1つあり、リネームもアーカイブも削除もできません。追加のワークスペースを作ると、メンバー・サービスアカウント・APIキー・リソース上限を個別に割り当てられます。IDはwrkspc_で始まり、1組織あたり既定で最大100個です(アーカイブ済みは数えません)。

Default Workspaceの扱いにはクセがあります。IDは他のワークスペースと同じwrkspc_形式で、レスポンスヘッダーにも出ます。ただしList Workspacesの結果に入るのはinclude_default=trueを付けたときだけです。APIキー・利用状況レポート・コストレポートでは、workspace_idがnullで返ります。

APIリファレンスのクエリ表にinclude_defaultは載っていません。WorkspacesとAuthenticationのページには、このパラメーターでDefault Workspaceを含められると書かれています。

このnullはDefault Workspace専用の印ではありません。すべてのワークスペースで使える複数ワークスペース対応のキーもnullになります。見分けるにはAPIキーのscopeフィールドを見ます。Default Workspaceに紐づくキーなら、scopeには本物のIDが入ります。

Claude Codeワークスペースの4つの特徴

組織のメンバーが初めてClaude CodeにConsoleアカウントでサインインすると、AnthropicがClaude Codeワークスペースを自動で作ってメンバーを追加します。以降にサインインするメンバーも同じ扱いです。

ワークスペースの作り方とAdmin API

作成できるのは組織管理者だけです。組織のユーザー・開発者をワークスペースに入れるのも管理者の作業で、セルフサービスでは参加できません。

Consoleでワークスペースを切り替えるときは、左上のWorkspacesセレクターを使います。

同じ操作はAdmin APIからも行えます。Admin APIが受け付けるのは、Admin APIキー、org:adminスコープのOAuthトークン、特定のワークスペースに縛られていない個人キーかサービスアカウントキーです。ワークスペースキーでは呼べません。

# Default Workspaceも含めて一覧する
curl "https://api.anthropic.com/v1/organizations/workspaces?limit=10&include_default=true" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -H "anthropic-version: 2023-06-01"
 
# メンバーをDeveloperとして追加する
curl -X POST "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/members" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"user_id": "user_01XyDMpzjS89pFZXqSFUBDr6", "workspace_role": "workspace_developer"}'

アーカイブは取り消せません。実行すると、そのワークスペース向けに作られたAPIキーがすべて数秒以内にアーカイブされます(Admin APIには「アーカイブ済み」として残ります)。複数ワークスペース対応のキーも、そのワークスペースでは動かなくなります。過去のデータはレポート用に残ります。

ワークスペースロールは5段階

ワークスペース内の権限は5段階です。

Workspace Billingは手動で割り当てられません。組織の請求ロールを持つメンバーに自動で付与されます。組織のユーザー・開発者に割り当てられるのは、Admin・Developer・Limited Developer・Userの4つです。

「入れない」「外せない」の原因は組織ロールにある

ワークスペースロールは、組織ロール(User・Admin・Owner・Primary Owner)とは別の階層です。組織ロールは組織全体の権限を決め、ワークスペースロールは各ワークスペースの中でだけ効きます。ただし一部は組織ロールから自動で継承されます。

• 組織管理者は、すべてのワークスペースでWorkspace Adminになります
• 組織の請求メンバーは、すべてのワークスペースでWorkspace Billingになります
• 組織のユーザー・開発者は、ワークスペースごとに明示的な追加が必要です
• サービスアカウントは、Settings > Service accountsで、アカウントのメニューか個別ページのAdd to workspaceから追加します。ワークスペース別に見たいときは、一覧をワークスペースで絞り込みます

症状別に原因を切り分けると次のとおりです。

Default Workspaceには、メンバー一覧がありません。アクセスは各メンバーの組織ロールに従って決まります。

APIキーはどのワークスペースで動くのか

すべてのAPIリクエストは、ちょうど1つのワークスペースで実行されます。そのワークスペースのリソースにしか触れません。どのワークスペースになるかはキーの種類で決まります。

公式のAuthenticationページは、ワークスペースキーをレガシーと位置づけています。新規の連携には、個人キーかサービスアカウントキーを勧める書き方です。共有・自動化のワークロード(CIや本番サービス)には、サービスアカウントを管理者に作ってもらう流れが示されています。

サービスアカウントキーには注意点があります。作成した本人がワークスペースから外れても、キーは動き続けます。止まるのは、サービスアカウントがアーカイブされたとき、または単一ワークスペース用のキーでそのワークスペースから外されたときです。

実際に届いたヘッダーで確かめる

レスポンスのanthropic-workspace-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'

値は利用状況・コストレポートのworkspace_idと突き合わせられます。Default Workspaceかどうかは、Admin API資格情報でGet Workspaceに渡して確かめます。Default Workspaceなら"name": "Default"で返ります。

ワークスペースごとに分かれるもの、分かれないもの

分離されるのは、Files APIのファイル、Batch APIのメッセージバッチ、Skills APIのスキルです。

分け方が違うものもあります。MCPトンネルはWorkload Identity Federation経由のworkspace:manage_tunnelsスコープ付きOAuthトークンで管理します。APIキーでは扱えません。トンネルはワークスペース内に作られ、ConsoleのMCP tunnels一覧もManaged Agentのサーバー選択も、現在のワークスペースのトンネルだけを表示します。ただしアクティブ数10本の上限は組織全体で共有です。組織の開発者は閲覧のみで、変更にはトンネル管理権限を持つロールが要ります。

プロンプトキャッシュの分離単位は、プラットフォームで違います。

Bedrockでは、ワークスペースを分けてもキャッシュは分かれず、組織内で共有されます。

上限とコストの集計

各ワークスペースの上限は、組織の上限以下にしか設定できません。Default Workspaceには設定できません。

ワークスペース側で何も設定しなければ、組織の上限がそのまま適用されます。ワークスペースの上限を足し合わせた値が組織の上限を超えていても、効くのは組織全体の上限です。現在の上限はRate Limits APIでも読めます。

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-01-01T00:00:00Z&\
ending_at=2026-01-08T00:00:00Z&\
workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\
group_by[]=workspace_id&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Usage and Cost APIでワークスペース別に集計するとき、Default Workspaceの分はworkspace_idがnullの行に入ります。「null = Default Workspace」と決め打ちすると誤集計になります。nullの行は別枠で扱い、必要ならキーのscopeで内訳を確かめる実装が安全です。

メンバーが離れたとき、キーはどうなるか

離職や異動でワークスペースから外したときの失効条件は、キーの種類ごとに前掲の比較のとおりです。ワークスペースキーは在籍と無関係に残るので、不要になったものはAPI keysページから自分で削除します。

組織そのものから外れた場合、個人キーはアーカイブされます。再招待されても過去のキーは復元されず、新規発行が必要です。再招待の手順はClaude Consoleにメンバーを招待する手順にあります。

キーの無効化と削除は性質が違います。無効化したキーはinactiveになり、再有効化でactiveに戻せます。削除は元に戻せず、キーはアーカイブされて、List API Keysにarchivedとして残ります。期限切れのキーは削除しかできません。

レガシーのワークスペースキーを置き換える

ワークスペースキーをサービスアカウントキーなどに替える手順は、公式が5段階で示しています。

新しくキーを作るときは有効期限も選びます。プリセットは3時間・1日・7日・30日で、カスタム期間とNeverもあります。組織に最大期限のポリシーがあると、プリセットとカスタム期間はその上限までに絞られ、Neverは選べません。期限は作成時にしか決められず、あとから変更できません。期限切れのキーは401のauthentication_errorを返し、再有効化はできません。

期限が近づくと、作成者にメールが届きます。寿命が14日以上のキーは期限の7日前、7日以上のキーは1日前です。寿命がそれより短いキーは、警告メールなしで切れます。Admin APIのexpires_at(期限なしはnull)で、期限を棚卸しできます。

ワークスペース分割の3つの型

分け方は大きく3つです。

• 環境分離: 開発は低めのレート制限、ステージングは本番に近い制限、本番は制限を絞らず監視を厚くする
• チーム・部門分離: エンジニアリングには開発者権限、データサイエンスには専用のAPIキー、サポートには限定的なアクセスを割り当てる
• プロジェクト分離: プロダクトごとにワークスペースを立て、利用量とコストを独立して追う

作る前に、請求・アクセス制御・使用量追跡の要件を洗い出し、用途が分かる名前(例: 「Production - 顧客チャットボット」)を付けます。メンバーの定期的な見直しも、公式のベストプラクティスに挙がっています。

まとめ

外せない・見えないと感じたら、先に組織ロールを疑います。集計のnullをDefault Workspaceと決め打ちしないことと、Claude Codeワークスペースをアーカイブしないことが、影響の大きい2点です。

外部Connectorにどの書き込み権限まで渡すかという権限設計は、ClaudeとLatticeを連携する方法でも扱っています。コストをワークスペース単位で追いたい場合は、Usage and Cost APIのgroup_by[]=workspace_idで集計します。