A Space is a browser session that belongs to one user. An agent works in a Space through the Agent Vault MCP tools.
Example Space
cURL
browser_space
Creates a Space for a user and starts its browser. The response arrives once the browser is ready.
cURL
| curl --request POST \ | |
| --url https://api.workos.com/agent-vault/spaces \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| --data '{ | |
| "user_id": "user_01E4ZCR3C56J083X43JQXF3JK5", | |
| "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT", | |
| "name": "Shipping workspace" | |
| }' |
| { | |
| "object": "browser_space", | |
| "id": "bspace_01JD3X9W4Q5Z8R7T6Y2N0M1KBC", | |
| "user_id": "user_01E4ZCR3C56J083X43JQXF3JK5", | |
| "name": "Shipping workspace", | |
| "status": "ready", | |
| "expires_at": "2026-11-13T19:05:00.000Z", | |
| "cleanup_status": "none" | |
| } |
POST/agent-vault /spaces
Returns
- 400 Bad Request: the body is missing a field, has an unknown field, or
nameis too long. - 401 Unauthorized: the user is not in the environment of the API key, or is not an active member of the organization.
- 403 Forbidden:
cdp_urlwas sent while Self-hosted is not selected for the environment, or the URL is not at one of its allowed origins. - 503 Service Unavailable: the browser could not be started, or the browser at
cdp_urlcould not be reached.
Lists a user’s Spaces in an organization.
cURL
| curl --request GET \ | |
| --url "https://api.workos.com/agent-vault/spaces?user_id=user_01E4ZCR3C56J083X43JQXF3JK5&organization_id=org_01EHZNVPK3SFK441A1RGBFSHRT" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| { | |
| "object": "list", | |
| "data": [ | |
| { | |
| "object": "browser_space", | |
| "id": "bspace_01JD3X9W4Q5Z8R7T6Y2N0M1KBC", | |
| "user_id": "user_01E4ZCR3C56J083X43JQXF3JK5", | |
| "name": "Shipping workspace", | |
| "status": "ready", | |
| "expires_at": "2026-11-13T19:05:00.000Z", | |
| "cleanup_status": "none" | |
| } | |
| ] | |
| } |
GET/agent-vault /spaces
Parameters
Returns object
- 401 Unauthorized: the user is not in the environment of the API key, or is not an active member of the organization.
Closes a Space. Every grant bound to the Space stops working at once, and the browser WorkOS started for it shuts down. An self-hosted browser keeps running.
The response is the Space with the status revoked.
cURL
| curl --request DELETE \ | |
| --url "https://api.workos.com/agent-vault/spaces/bspace_01JD3X9W4Q5Z8R7T6Y2N0M1KBC?user_id=user_01E4ZCR3C56J083X43JQXF3JK5&organization_id=org_01EHZNVPK3SFK441A1RGBFSHRT" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| { | |
| "object": "browser_space", | |
| "id": "bspace_01JD3X9W4Q5Z8R7T6Y2N0M1KBC", | |
| "user_id": "user_01E4ZCR3C56J083X43JQXF3JK5", | |
| "name": "Shipping workspace", | |
| "status": "revoked", | |
| "expires_at": "2026-11-13T19:05:00.000Z", | |
| "cleanup_status": "pending" | |
| } |
- 401 Unauthorized: the user is not in the environment of the API key, or is not an active member of the organization.
- 403 Forbidden: the Space does not belong to the user.
- 404 Not Found: no Space has that ID.