workspaces changedmanage-claude/workspaces
Nearest release: v2.1.312, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+39added
Lines−39removed
From line
13
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits25to this page, all time
The whole hunk
from line 13, old and new numbered
/
from line 13
1313Key characteristics:
1414
1515* **Workspace identifiers** use the `wrkspc_` prefix (for example, `wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ`).
16* **Maximum 100 workspaces** for each organization by default (archived workspaces don't count). Contact your account team if you need more.
17* **Default Workspace** has a `wrkspc_` ID like any other workspace (returned in the [`anthropic-workspace-id` response header](https://platform.claude.com/docs/en/manage-claude/workspaces#identify-the-workspace-behind-an-api-response) and accepted by [Get Workspace](https://platform.claude.com/docs/en/api/organization/workspaces/retrieve)), but it appears in [List Workspaces](https://platform.claude.com/docs/en/api/organization/workspaces/list) results only when you pass `include_default=true`, and usage reports and cost reports show `null` for its `workspace_id` (an API key's `scope` field carries the real ID for a key bound to the Default Workspace).
18* **API keys** can be scoped to a single workspace. In this case, they can only access resources within that workspace. Other API keys aren't scoped to a workspace. With one of these keys, send a [workspace ID header](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) on each request to choose the workspace. The key's user or service account must have access to that workspace.
16* **Maximum 100 workspaces** for each organization by default (archived workspaces don’t count). Contact your account team if you need more.
17* **Default Workspace** has a `wrkspc_` ID like any other workspace (returned in the [`anthropic-workspace-id` response header](https://platform.claude.com/docs/en/manage-claude/workspaces#identify-the-workspace-behind-an-api-response) and accepted by [Get Workspace](https://platform.claude.com/docs/en/api/organization/workspaces/retrieve)), but it appears in [List Workspaces](https://platform.claude.com/docs/en/api/organization/workspaces/list) results only when you pass `include_default=true`, and usage reports and cost reports show `null` for its `workspace_id` (an API key’s `scope` field carries the real ID for a key bound to the Default Workspace).
18* **API keys** can be scoped to a single workspace. In this case, they can only access resources within that workspace. Other API keys aren’t scoped to a workspace. With one of these keys, send a [workspace ID header](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) on each request to choose the workspace. The key’s user or service account must have access to that workspace.
1919
2020### Claude Code workspace
2121
from line 25
2525
2626* Claude Code mints a per-user API key in this workspace at sign-in. You cannot create keys in it manually from the Console.
2727* A Claude Code key stops working if its owner is removed from the workspace or organization, unlike a workspace key.
28* Claude Code usage is rate-limited separately, and admins can cap its share of the organization's limits under [Rate limits in the Claude Console](https://platform.claude.com/usage/limits).
28* Claude Code usage is rate-limited separately, and admins can cap its share of the organization’s limits under [Rate limits in the Claude Console](https://platform.claude.com/usage/limits).
2929* It is the only workspace that supports per-user monthly spend limits.
3030
3131<Warning>
from line 36
3636
3737Members can have different roles in each workspace, allowing fine-grained access control.
3838
39| Role | Permissions |
40| --------------------------- | ----------------------------------------------------------------------------------------------- |
41| Workspace User | Use playground only |
42| Workspace Limited Developer | Create and manage API keys, use the API. Cannot access session tracing views or download files. |
43| Workspace Developer | Create and manage API keys, use the API |
44| Workspace Admin | Full control over workspace settings and members |
45| Workspace Billing | View workspace billing information (inherited from organization billing role) |
39| Role | Permissions |
40| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41| Workspace User | Use playground only |
42| Workspace Limited Developer | Create and manage API keys, use the API<br />For [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) in the Claude Console, members with this role cannot open or start sessions, open memory stores, or manage deployments. They also cannot download or delete files on the Console’s [Files](https://platform.claude.com/files) page. These limits apply only to the Console’s interface, not to the API. |
43| Workspace Developer | Create and manage API keys, use the API |
44| Workspace Admin | Full control over workspace settings and members |
45| Workspace Billing | View workspace billing information (inherited from organization billing role) |
4646
4747### Role inheritance
4848
from line 49
4949* **Organization admins** automatically receive Workspace Admin access to all workspaces.
5050* **Organization billing members** automatically receive Workspace Billing access to all workspaces.
5151* **Organization users and developers** must be explicitly added to each workspace.
52* **Service accounts** are added to workspaces on the [Service accounts](https://platform.claude.com/settings/service-accounts) page (`platform.claude.com/settings/service-accounts`) in the Claude Console: select **Add to workspace** in the account's menu or on its own page. To see the accounts in one workspace, filter the list by workspace.
52* **Service accounts** are added to workspaces on the [Service accounts](https://platform.claude.com/settings/service-accounts) page (`platform.claude.com/settings/service-accounts`) in the Claude Console: select **Add to workspace** in the account’s menu or on its own page. To see the accounts in one workspace, filter the list by workspace.
5353
5454<Note>
55 The Workspace Billing role cannot be manually assigned. It's inherited from having the organization billing role.
55 The Workspace Billing role cannot be manually assigned. It’s inherited from having the organization billing role.
5656</Note>
5757
5858## Managing workspaces
from line 91
9191
9292#### Edit workspace details
9393
94To modify a workspace's name or color:
94To modify a workspace’s name or color:
9595
96961. Select the workspace from the list.
97972. Open the **More actions** menu (three dots) and select **Edit details**.
from line 111
111111#### Remove members from a workspace
112112
1131131. On the [Members](https://platform.claude.com/settings/members) page in the Claude Console, select the workspace from the **Workspace** dropdown menu. If it shows **All**, **Remove member** removes the member from your organization instead.
1142. At the end of the member's row, open the **More actions** menu (three dots) and select **Remove member**.
1142. At the end of the member’s row, open the **More actions** menu (three dots) and select **Remove member**.
1151153. Click **Remove** to confirm.
116116
117117<Note>
from line 120
120120
121121#### Set workspace limits
122122
123You set a workspace's rate limits and spend limits in different places:
123You set a workspace’s rate limits and spend limits in different places:
124124
125125* **Rate limits:** Under [Rate limits in the Claude Console](https://platform.claude.com/usage/limits), select the workspace from the **Workspace** dropdown menu and click **Edit** next to a model to set limits for requests per minute, input tokens, or output tokens.
126126* **Spend limits:** On the [Workspaces](https://platform.claude.com/settings/workspaces) page in the Claude Console, select the workspace. In the panel that opens, click **Spend limits** to cap monthly spending and configure alerts when spending reaches certain thresholds.
from line 134
134134* Cannot be undone
135135
136136<Warning>
137 Archiving a workspace archives every API key created for that workspace within seconds (they remain listed in the Admin API as archived), and keys that aren't scoped to a workspace can no longer act in it. This action cannot be undone. If you archive the [Claude Code workspace](https://platform.claude.com/docs/en/manage-claude/workspaces#claude-code-workspace), members of your organization can no longer sign in to Claude Code through Console billing.
137 Archiving a workspace archives every API key created for that workspace within seconds (they remain listed in the Admin API as archived), and keys that aren’t scoped to a workspace can no longer act in it. This action cannot be undone. If you archive the [Claude Code workspace](https://platform.claude.com/docs/en/manage-claude/workspaces#claude-code-workspace), members of your organization can no longer sign in to Claude Code through Console billing.
138138</Warning>
139139
140140### Using the Admin API
from line 142
142142Programmatically manage workspaces using the [Admin API](https://platform.claude.com/docs/en/manage-claude/admin-api).
143143
144144<Note>
145 Admin API endpoints accept an [Admin API key](https://platform.claude.com/docs/en/manage-claude/admin-api-keys), an `org:admin` OAuth token, or a personal or service account key that isn't scoped to a specific workspace. Workspace keys don't work there. See [Authentication](https://platform.claude.com/docs/en/manage-claude/admin-api#authentication).
145 Admin API endpoints accept an [Admin API key](https://platform.claude.com/docs/en/manage-claude/admin-api-keys), an `org:admin` OAuth token, or a personal or service account key that isn’t scoped to a specific workspace. Workspace keys don’t work there. See [Authentication](https://platform.claude.com/docs/en/manage-claude/admin-api#authentication).
146146</Note>
147147
148148The following SDK and CLI examples construct the default client, which reads the Admin API key from the `ANTHROPIC_API_KEY` environment variable; the SDK exposes these endpoints under `client.organization.workspaces` (csharp, go: `client.Organization.Workspaces`; java: `client.organization().workspaces()`; php: `$client->organization->workspaces`). SDK list methods fetch further pages on demand, so `limit` sets the page size; the PHP, Ruby, and curl examples return one page.
from line 581
581581 ```
582582</CodeGroup>
583583
584Update a member's role:
584Update a member’s role:
585585
586586<CodeGroup>
587587 ```bash cURL
from line 826
826826Every request runs in exactly one workspace and can only access resources within that workspace. Which workspace depends on the [key type](https://platform.claude.com/docs/en/manage-claude/authentication#key-types):
827827
828828* A **workspace key** (a legacy key without an owner) belongs to the workspace it was created in and always runs there.
829* A **personal key** or **service account key** acts as its user or service account. A single-workspace key always runs in the workspace chosen when it was created. A key that isn't scoped to a workspace runs in the workspace named by each request's `anthropic-workspace-id` header. Accounts must have access to the workspace to use it.
829* A **personal key** or **service account key** acts as its user or service account. A single-workspace key always runs in the workspace chosen when it was created. A key that isn’t scoped to a workspace runs in the workspace named by each request’s `anthropic-workspace-id` header. Accounts must have access to the workspace to use it.
830830
831831Resources scoped to workspaces include:
832832
from line 837
837837Some resources are managed differently:
838838
839839* **[MCP tunnels](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview)** are managed with a `workspace:manage_tunnels` OAuth token obtained through [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation), not an API key. Tunnels are created in a workspace, and the Console **MCP tunnels** list and the Managed Agent server picker show tunnels in the current workspace only; the cap of 10 active tunnels applies organization-wide. Tunnel management requires a role with tunnel management permissions; organization developers can view but not change them.
840* **Workspaces** themselves and **organization members** are managed at the organization level through the [Admin API](https://platform.claude.com/docs/en/manage-claude/admin-api), using an Admin API key, an `org:admin` OAuth token, or a personal or service account key that isn't scoped to a specific workspace.
840* **Workspaces** themselves and **organization members** are managed at the organization level through the [Admin API](https://platform.claude.com/docs/en/manage-claude/admin-api), using an Admin API key, an `org:admin` OAuth token, or a personal or service account key that isn’t scoped to a specific workspace.
841841
842To look up your organization's workspace IDs, call the [List Workspaces](https://platform.claude.com/docs/en/api/organization/workspaces/list) endpoint (pass `include_default=true` to include the Default Workspace) or find them on the [Workspaces](https://platform.claude.com/settings/workspaces) page in the Claude Console.
842To look up your organization’s workspace IDs, call the [List Workspaces](https://platform.claude.com/docs/en/api/organization/workspaces/list) endpoint (pass `include_default=true` to include the Default Workspace) or find them on the [Workspaces](https://platform.claude.com/settings/workspaces) page in the Claude Console.
843843
844844<Note>
845845 [Prompt caches](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) are also isolated by workspace on the Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry). On Amazon Bedrock and Claude Models on Google Cloud (Google managed), prompt caches are isolated by organization.
from line 847
847847
848848## Identify the workspace behind an API response
849849
850Claude API responses include an `anthropic-workspace-id` header alongside the `request-id` and `anthropic-organization-id` [response headers](https://platform.claude.com/docs/en/api/overview#response-headers). Its value is the `wrkspc_`-prefixed ID of the workspace that the request's API key or access token resolved to, including when that workspace is the Default Workspace. For example, a successful response includes headers like these:
850Claude API responses include an `anthropic-workspace-id` header alongside the `request-id` and `anthropic-organization-id` [response headers](https://platform.claude.com/docs/en/api/overview#response-headers). Its value is the `wrkspc_`-prefixed ID of the workspace that the request’s API key or access token resolved to, including when that workspace is the Default Workspace. For example, a successful response includes headers like these:
851851
852852```http
853853HTTP/1.1 200 OK
from line 856
856856anthropic-workspace-id: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ
857857```
858858
859The header is absent when the credential doesn't resolve to a workspace (for example, on Admin API requests) or when the request fails before authentication completes, such as a 401 error.
859The header is absent when the credential doesn’t resolve to a workspace (for example, on Admin API requests) or when the request fails before authentication completes, such as a 401 error.
860860
861861The following examples send a Messages API request and read the workspace ID from the response headers:
862862
from line 1009
10091009
10101010With the workspace ID from a response, you can:
10111011
1012* Confirm which workspace's usage, cost, and [rate limits](https://platform.claude.com/docs/en/api/rate-limits) the request counted toward
1012* Confirm which workspace’s usage, cost, and [rate limits](https://platform.claude.com/docs/en/api/rate-limits) the request counted toward
10131013* Match it against the `workspace_id` field in [Usage and Cost API](https://platform.claude.com/docs/en/manage-claude/usage-cost-api) reports, which is `null` for the Default Workspace. Also match it against the `scope` field of API keys in the [Admin API](https://platform.claude.com/docs/en/manage-claude/admin-api), which carries the real ID of the workspace a key is bound to, including the Default Workspace
1014* Check whether it's your Default Workspace's ID by passing it to [Get Workspace](https://platform.claude.com/docs/en/api/organization/workspaces/retrieve) with an [Admin API key](https://platform.claude.com/docs/en/manage-claude/admin-api-keys): the Default Workspace comes back with `"name": "Default"`, even though [List Workspaces](https://platform.claude.com/docs/en/api/organization/workspaces/list) omits it unless you pass `include_default=true`
1015* Open that workspace in the [Console](https://platform.claude.com/settings/workspaces) to find the request's resources, such as sessions, files, message batches, and skills
1014* Check whether it’s your Default Workspace’s ID by passing it to [Get Workspace](https://platform.claude.com/docs/en/api/organization/workspaces/retrieve) with an [Admin API key](https://platform.claude.com/docs/en/manage-claude/admin-api-keys): the Default Workspace comes back with `"name": "Default"`, even though [List Workspaces](https://platform.claude.com/docs/en/api/organization/workspaces/list) omits it unless you pass `include_default=true`
1015* Open that workspace in the [Console](https://platform.claude.com/settings/workspaces) to find the request’s resources, such as sessions, files, message batches, and skills
10161016
10171017## Workspace limits
10181018
from line 1020
10201020
10211021### Setting workspace limits
10221022
1023You can set workspace limits lower than (but not higher than) your organization's limits:
1023You can set workspace limits lower than (but not higher than) your organization’s limits:
10241024
10251025* **Spend limits:** Cap monthly spending for a workspace. To set these, go to the [Workspaces](https://platform.claude.com/settings/workspaces) page (`platform.claude.com/settings/workspaces`) in the Claude Console and select the workspace. In the panel that opens, click **Spend limits**.
10261026* **Rate limits:** Limit requests per minute, input tokens per minute, or output tokens per minute. To set these, go to [Rate limits in the Claude Console](https://platform.claude.com/usage/limits), select the workspace from the **Workspace** dropdown menu, and click **Edit** next to a model.
from line 1027
10271027
10281028<Note>
10291029 - You cannot set spend limits on the Default Workspace.
1030 - If not set, workspace limits match the organization's limits.
1030 - If not set, workspace limits match the organization’s limits.
10311031 - Organization-wide limits always apply, even if workspace limits add up to more.
10321032</Note>
10331033
from line 1078
10781078
10791079<Steps>
10801080 <Step title="Plan your workspace structure">
1081 Consider how you'll organize workspaces before creating them. Think about billing, access control, and usage tracking needs.
1081 Consider how you’ll organize workspaces before creating them. Think about billing, access control, and usage tracking needs.
10821082 </Step>
10831083
10841084 <Step title="Use meaningful names">
1085 Name workspaces clearly to indicate their purpose (for example, "Production - Customer Chatbot" or "Dev - Internal Tools").
1085 Name workspaces clearly to indicate their purpose (for example, “Production - Customer Chatbot” or “Dev - Internal Tools”).
10861086 </Step>
10871087
10881088 <Step title="Set appropriate limits">
from line 1101
11011101## FAQ
11021102
11031103<AccordionGroup>
1104 <Accordion title="What's the Default Workspace?">
1105 Every organization has a "Default Workspace" that cannot be renamed, archived, or deleted. Like every workspace, it has a `wrkspc_` ID: the API returns it in the [`anthropic-workspace-id` response header](https://platform.claude.com/docs/en/manage-claude/workspaces#identify-the-workspace-behind-an-api-response), and you can pass it to [Get Workspace](https://platform.claude.com/docs/en/api/organization/workspaces/retrieve) and [Update Workspace](https://platform.claude.com/docs/en/api/organization/workspaces/update). It has no member list of its own, because access to it follows each member's organization role. It appears in [List Workspaces](https://platform.claude.com/docs/en/api/organization/workspaces/list) results only when you pass `include_default=true`, and usage reports and cost reports that belong to it show `null` for `workspace_id`. For an API key that belongs to it, the key's `scope` field carries the workspace's real ID.
1104 <Accordion title="What’s the Default Workspace?">
1105 Every organization has a “Default Workspace” that cannot be renamed, archived, or deleted. Like every workspace, it has a `wrkspc_` ID: the API returns it in the [`anthropic-workspace-id` response header](https://platform.claude.com/docs/en/manage-claude/workspaces#identify-the-workspace-behind-an-api-response), and you can pass it to [Get Workspace](https://platform.claude.com/docs/en/api/organization/workspaces/retrieve) and [Update Workspace](https://platform.claude.com/docs/en/api/organization/workspaces/update). It has no member list of its own, because access to it follows each member’s organization role. It appears in [List Workspaces](https://platform.claude.com/docs/en/api/organization/workspaces/list) results only when you pass `include_default=true`, and usage reports and cost reports that belong to it show `null` for `workspace_id`. For an API key that belongs to it, the key’s `scope` field carries the workspace’s real ID.
11061106 </Accordion>
11071107
1108 <Accordion title="What's the Claude Code workspace?">
1109 Anthropic creates the Claude Code workspace automatically the first time a member of your organization signs in to Claude Code with their Console account. It isolates Claude Code's API keys, usage, and rate limits from your other workloads. See [Claude Code workspace](https://platform.claude.com/docs/en/manage-claude/workspaces#claude-code-workspace) for details.
1108 <Accordion title="What’s the Claude Code workspace?">
1109 Anthropic creates the Claude Code workspace automatically the first time a member of your organization signs in to Claude Code with their Console account. It isolates Claude Code’s API keys, usage, and rate limits from your other workloads. See [Claude Code workspace](https://platform.claude.com/docs/en/manage-claude/workspaces#claude-code-workspace) for details.
11101110 </Accordion>
11111111
11121112 <Accordion title="Are there limits on workspaces?">
1113 Yes. Each organization can have up to 100 workspaces by default, and archived workspaces don't count toward this limit. If you need more, contact your account team.
1113 Yes. Each organization can have up to 100 workspaces by default, and archived workspaces don’t count toward this limit. If you need more, contact your account team.
11141114 </Accordion>
11151115
11161116 <Accordion title="How do organization roles affect workspace access?">
from line 1118
11181118 </Accordion>
11191119
11201120 <Accordion title="Which roles can be assigned in workspaces?">
1121 Organization users and developers can be assigned Workspace Admin, Workspace Developer, Workspace Limited Developer, or Workspace User roles. The Workspace Billing role cannot be manually assigned; it's inherited from having the organization `billing` role.
1121 Organization users and developers can be assigned Workspace Admin, Workspace Developer, Workspace Limited Developer, or Workspace User roles. The Workspace Billing role cannot be manually assigned; it’s inherited from having the organization `billing` role.
11221122 </Accordion>
11231123
1124 <Accordion title="Can organization admin or billing members' workspace roles be changed?">
1124 <Accordion title="Can organization admin or billing members’ workspace roles be changed?">
11251125 Organization admins and billing members cannot have their workspace roles changed or be removed from workspaces while they hold those organization roles (with one exception: billing members can be upgraded to a Workspace Admin role). For everyone else covered by this constraint, change their organization role first to change their workspace access.
11261126 </Accordion>
11271127
No line in this hunk matches that.