工作區

「Workspaces」（工作區）提供了一種在組織內組織 API 使用情況的方式。使用工作區來區隔不同的專案、環境或團隊，同時維持集中式的計費與管理。

工作區的運作方式

每個組織都有一個 Default Workspace（預設工作區），它無法被重新命名、封存或刪除。當您建立額外的工作區時，可以為每個工作區指派成員、服務帳戶、API 金鑰和資源限制。

主要特性：

• 工作區識別碼使用 wrkspc_ 前綴（例如 wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ）
• 每個組織預設最多 100 個工作區（已封存的工作區不計入）；如果您需要更多，請聯繫您的帳戶團隊
• Default Workspace 與其他工作區一樣擁有 wrkspc_ ID（會在 anthropic-workspace-id 回應標頭中回傳，並可被 Get Workspace 接受），但它不會出現在 List Workspaces 的結果中，且 API 金鑰、使用量報告和成本報告的 workspace_id 會顯示為 null，全工作區 API 金鑰也是如此（API 金鑰的 scope 欄位可以區分兩者；對於綁定到 Default Workspace 的金鑰，該欄位會帶有真實的 ID）
• API 金鑰可以限定於單一工作區。在這種情況下，它們只能存取該工作區內的資源。某些 API 金鑰可以被授予跨多個工作區的權限，並提供工作區 ID 標頭來存取該工作區內的資源

Claude Code 工作區

當您組織中的成員首次使用其 Claude Console 帳戶登入 Claude Code 時，Anthropic 會自動在組織中建立一個 Claude Code 工作區，並將該成員加入其中。之後每位登入 Claude Code 的成員都會以相同方式被加入。

Claude Code 工作區將 Claude Code 的流量與您的其他 API 工作負載分開：

• Claude Code 會在登入時於此工作區中為每位使用者產生一個 API 金鑰。您無法從 Console 手動在其中建立金鑰。
• 與工作區金鑰不同，如果 Claude Code 金鑰的擁有者被從工作區或組織中移除，該金鑰就會停止運作。
• Claude Code 的使用量會單獨進行速率限制，管理員可以在設定 > 工作區下限制其佔用組織限制的比例。
• 它是唯一支援每位使用者每月支出限制的工作區。

工作區角色與權限

成員在每個工作區中可以擁有不同的角色，從而實現細緻的存取控制。

角色繼承

• 組織管理員會自動獲得所有工作區的 Workspace Admin 存取權限
• 組織計費成員會自動獲得所有工作區的 Workspace Billing 存取權限
• 組織使用者和開發者必須被明確加入每個工作區
• 服務帳戶可從設定 → 服務帳戶中的服務帳戶頁面，或從工作區的服務帳戶分頁加入工作區

管理工作區

使用 Console

在 Claude Console 中建立和管理工作區。

建立工作區

1. 1

   開啟工作區設定

   在 Claude Console 中，前往設定 > 工作區。

2. 2

   建立工作區

   點擊建立工作區。

3. 3

   設定工作區

   輸入工作區名稱並選擇一個顏色以便視覺識別。

4. 4

   建立該工作區

   點擊建立以完成。

編輯工作區詳細資訊

若要修改工作區的名稱或顏色：

1. 從清單中選擇該工作區。
2. 點擊省略號選單（...）並選擇編輯詳細資訊。
3. 更新名稱或顏色並儲存您的變更。

將成員加入工作區

1. 前往工作區的成員分頁。
2. 點擊加入工作區。
3. 選擇一位組織成員並為其指派工作區角色。
4. 確認加入。

若要移除成員，請點擊其名稱旁的垃圾桶圖示。

設定工作區限制

每個工作區的設定將這些限制分為兩個分頁：

• 速率限制：在速率限制分頁上，為每個模型層級設定每分鐘請求數、輸入 token 或輸出 token 的限制
• 支出限制：在支出限制分頁上，設定每月支出上限，並設定當支出達到特定門檻時的警示

封存工作區

若要封存工作區，請點擊省略號選單（...）並選擇封存。封存會：

• 保留歷史資料以供報告使用
• 停用該工作區並封存為其建立的每個 API 金鑰
• 無法復原

使用 Admin API

使用 Admin API 以程式化方式管理工作區。

以下 SDK 和 CLI 範例會建構預設用戶端，該用戶端會從 ANTHROPIC_API_KEY 環境變數讀取 Admin API 金鑰；SDK 在 client.beta.organization.workspaces 下公開這些端點。SDK 的 list 方法會依需求擷取後續頁面，因此 limit 設定的是頁面大小；PHP、Ruby 和 curl 範例則回傳單一頁面。

建立工作區：

client = anthropic.Anthropic()

workspace = client.beta.organization.workspaces.create(name="Production")

print(f"id: {workspace.id}")
print(f"name: {workspace.name}")

列出工作區：

client = anthropic.Anthropic()

workspaces = client.beta.organization.workspaces.list(limit=10, include_archived=False)

for workspace in workspaces:
    print(f"{workspace.id}: {workspace.name}")

封存工作區：

client = anthropic.Anthropic()

workspace = client.beta.organization.workspaces.archive(
    "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
)

print(f"id: {workspace.id}")
print(f"archived_at: {workspace.archived_at}")

如需完整的參數詳細資訊和回應結構描述，請參閱 Workspaces API 參考文件。

管理工作區成員

將成員加入工作區：

client = anthropic.Anthropic()

member = client.beta.organization.workspaces.members.add(
    "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    user_id="user_01XyDMpzjS89pFZXqSFUBDr6",
    workspace_role="workspace_developer",
)

print(f"user_id: {member.user_id}")
print(f"workspace_role: {member.workspace_role}")

更新成員的角色：

client = anthropic.Anthropic()

member = client.beta.organization.workspaces.members.update(
    "user_01XyDMpzjS89pFZXqSFUBDr6",
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    workspace_role="workspace_admin",
)

print(f"user_id: {member.user_id}")
print(f"workspace_role: {member.workspace_role}")

從工作區移除成員：

client = anthropic.Anthropic()

removed_member = client.beta.organization.workspaces.members.remove(
    "user_01XyDMpzjS89pFZXqSFUBDr6",
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
)

print(f"user_id: {removed_member.user_id}")

如需完整的參數詳細資訊，請參閱 Workspace Members API 參考文件。

API 金鑰與資源範圍

每個請求都恰好在一個工作區中執行，且只能存取該工作區內的資源。在哪個工作區執行取決於金鑰類型：

• 工作區金鑰（沒有擁有者的舊版金鑰）屬於建立它的工作區，並且始終在該處執行。
• 個人金鑰或服務帳戶金鑰以其使用者或服務帳戶的身分運作。單一工作區金鑰始終在建立時所選擇的工作區中執行。多工作區金鑰則在每個請求的 anthropic-workspace-id 標頭所指定的工作區中執行。帳戶必須擁有該工作區的存取權限才能使用它。

限定於工作區的資源包括：

• 透過 Files API 建立的檔案
• 透過 Batch API 建立的訊息批次
• 透過 Skills API 建立的 Skills

某些資源的管理方式不同：

• **MCP 通道**是使用透過 Workload Identity Federation 取得的 workspace:manage_tunnels OAuth token 來管理，而非 API 金鑰。通道是在工作區中建立的，Console 的 MCP 通道清單和 Managed Agent 伺服器選擇器僅顯示目前工作區中的通道；10 個作用中通道的上限適用於整個組織。通道管理需要具有通道管理權限的角色；組織開發者可以檢視但無法變更它們。
• 工作區本身和組織成員是透過 Admin API 在組織層級進行管理，使用 Admin API 金鑰、org:admin OAuth token，或未限定於特定工作區的個人或服務帳戶金鑰。

若要查詢您組織的工作區 ID，請呼叫 List Workspaces 端點，或在 Claude Console 中找到它們。

識別 API 回應背後的工作區

Claude API 回應除了 request-id 和 anthropic-organization-id 回應標頭之外，還包含一個 anthropic-workspace-id 標頭。其值是該請求的 API 金鑰或存取 token 所解析到的工作區之 wrkspc_ 前綴 ID，包括該工作區是 Default Workspace 的情況。例如，一個成功的回應會包含如下標頭：

HTTP/1.1 200 OK
request-id: req_018EeWyXxfu5pfWkrYcMdjWG
anthropic-organization-id: 0d0e7a3b-52f1-4c7e-9a51-3f6f2f7c1b9e
anthropic-workspace-id: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

當憑證未解析到工作區時（例如在 Admin API 請求中），或當請求在驗證完成前失敗時（例如 401 錯誤），此標頭不會出現。

以下範例會傳送一個 Messages API 請求，並從回應標頭中印出工作區 ID：

client = anthropic.Anthropic()

response = client.messages.with_raw_response.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
workspace_id = response.headers.get("anthropic-workspace-id")
print(f"Workspace ID: {workspace_id}")

Workspace ID: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

相同的存取器也可以從其他 Claude API 端點讀取此標頭，包括 Claude Managed Agents API。例如，從建立工作階段的回應中讀取 anthropic-workspace-id，以記錄該工作階段屬於哪個工作區。

有了回應中的工作區 ID，您可以：

• 確認該請求計入了哪個工作區的使用量、成本和速率限制
• 將其與 Usage and Cost API 報告中以及 Admin API 物件（例如 API 金鑰）上的 workspace_id 欄位進行比對（兩者對於 Default Workspace 都會回報 null，API 金鑰對於全工作區金鑰也是如此；API 金鑰的 scope 欄位可以區分兩者，且對於綁定到單一工作區的金鑰，會帶有該工作區的真實 ID）
• 透過使用 Admin API 金鑰將其傳遞給 Get Workspace，檢查它是否為您的 Default Workspace 的 ID：Default Workspace 會回傳 "name": "Default"，即使 List Workspaces 會省略它
• 在 Console 中開啟該工作區，以找到該請求的資源，例如工作階段、檔案、訊息批次和 skills

工作區限制

您可以為每個工作區設定自訂的支出和速率限制，以防止過度使用並確保公平的資源分配。

設定工作區限制

您可以將工作區限制設定為低於（但不能高於）您組織的限制：

• 支出限制：設定工作區的每月支出上限。請在 Claude Console 中該工作區的支出限制設定分頁上進行設定。
• 速率限制：限制每分鐘請求數、每分鐘輸入 token 數或每分鐘輸出 token 數。請在 Claude Console 中該工作區的速率限制設定分頁上進行設定。

如需有關速率限制及其運作方式的詳細資訊，請參閱速率限制。您也可以使用 Rate Limits API 以程式化方式讀取您目前的組織和工作區速率限制。

使用量與成本追蹤

使用 Usage and Cost API 依工作區追蹤使用量與成本：

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-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"

歸屬於 Default Workspace 的使用量與成本，其 workspace_id 的值為 null。

常見使用案例

環境區隔

為開發、預備和正式環境建立個別的工作區：

團隊或部門隔離

將工作區指派給不同團隊，以進行成本分攤與存取控制：

• 具有開發者存取權限的工程團隊
• 擁有自己 API 金鑰的資料科學團隊
• 對客戶工具具有有限存取權限的支援團隊

以專案為基礎的組織方式

為特定專案或產品建立工作區，以分別追蹤使用量與成本。

最佳實務

1. 1

   規劃您的工作區結構

   在建立工作區之前，先考慮您將如何組織它們。思考計費、存取控制和使用量追蹤的需求。

2. 2

   使用有意義的名稱

   清楚地命名工作區以表明其用途（例如「Production - Customer Chatbot」或「Dev - Internal Tools」）。

3. 3

   設定適當的限制

   設定支出和速率限制，以防止意外成本並確保公平的資源分配。

4. 4

   定期稽核存取權限

   定期檢視工作區成員資格，以確保只有適當的使用者擁有存取權限。

5. 5

   監控使用量

   使用 Usage and Cost API 追蹤工作區層級的用量。

常見問題

另請參閱

• Admin API
• Admin API 參考文件
• 速率限制
• Usage and Cost API