<!-- llms.txt: https://workos.com/llms.txt -->
<!-- feedback.md: https://workos.com/docs/feedback.md -->

# Space

A Space is a browser session that belongs to one user. An agent works in a Space through the [Agent Vault MCP tools](https://workos.com/docs/reference/agent-vault/mcp).

:::code-group{title="Example Space"}

```json language="curl"
{
  "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"
}
```

:::

## Close a Space

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](https://workos.com/docs/agent-vault/self-hosted-browser) keeps running.

The response is the Space with the status `revoked`.

:::code-group

```bash language="curl" title="Request" tab="1"
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"
```

```json language="json" title="Response" tab="2"
{
  "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"
}
```

:::

### Error responses

- **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.

## Create a Space

Creates a Space for a user and starts its browser. The response arrives once the browser is ready.

:::code-group

```bash language="curl" title="Request" tab="1"
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"
  }'
```

```json language="json" title="Response" tab="2"
{
  "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"
}
```

:::

### Error responses

- **400 Bad Request**: the body is missing a field, has an unknown field, or `name` is 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_url` was 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_url` could not be reached.

## List Spaces

Lists a user's Spaces in an organization.

:::code-group

```bash language="curl" title="Request" tab="1"
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"
```

```json language="json" title="Response" tab="2"
{
  "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"
    }
  ]
}
```

:::

### Error responses

- **401 Unauthorized**: the user is not in the environment of the API key, or is not an active member of the organization.

### browser_space

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "browser_space" | Yes | Distinguishes the Space object. |
| `id` | string | Yes | Unique identifier of the Space. |
| `user_id` | string | Yes | ID of the user the Space belongs to. |
| `name` | string | Yes | The name given to the Space when it was created. |
| `status` | "creating" \| "ready" \| "authenticating" \| "revoked" \| "closed" \| "failed" | Yes | The state of the Space. `creating`: the browser is starting. `ready`: the browser is running and an agent can use it. `authenticating`: a sign-in is running in the Space. `revoked` or `closed`: the Space has ended and can't be used again. `failed`: the browser could not be started. |
| `expires_at` | string | Yes | ISO 8601 timestamp of when the Space expires. A Space expires ten minutes after its last browser work, and never later than one hour after it was created. |
| `cleanup_status` | "none" \| "pending" \| "completed" | Yes | Whether the browser behind an ended Space has been shut down: `none` while the Space is in use, `pending` while the browser is shutting down, and `completed` once it has. |

### DELETE /agent-vault/spaces/{id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier of the Space. |
| `user_id` | string | Yes | ID of the signed-in user the request acts for, as a query parameter. |
| `organization_id` | string | No | ID of the organization the user works in, as a query parameter. Omit it for a user who works outside any organization. |

### POST /agent-vault/spaces

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | string | Yes | ID of the signed-in user the request acts for. |
| `organization_id` | string | No | ID of the organization the user works in. Saved logins and Spaces belong to the user within that organization. Omit it for a user who works outside any organization. |
| `name` | string | Yes | A name for the Space, up to 120 characters. It is shown in the WorkOS Dashboard. |
| `cdp_url` | string | No | The Chrome DevTools Protocol URL of a browser you run. When set, the Space runs in that browser instead of one WorkOS creates. See [Self-hosted browser](/agent-vault/self-hosted-browser). |

### GET /agent-vault/spaces

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | string | Yes | ID of the signed-in user the request acts for, as a query parameter. |
| `organization_id` | string | No | ID of the organization the user works in, as a query parameter. Omit it for a user who works outside any organization. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `object` | "list" | Indicates this is a list response. |
| `data` | object[] | Array of the user's [Spaces](/reference/agent-vault/space), including ones that have ended. |