> ## Documentation Index
> Fetch the complete documentation index at: https://docs.domesystems.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

> Create workspaces, manage members, and configure act-as enforcement and policy freshness

Create and delete workspaces, assign member roles, configure act-as identity enforcement and policy freshness, and provision sandboxes. These 11 tools span three permission tiers: list/get are visible to any caller with an active context; member, act-as, freshness, and delete operations require workspace `workspace.manage` or `config.manage`; workspace creation and sandbox provisioning require tenant- or org-level permissions.

## Workspaces List

`dome_workspaces_list`

List all workspaces in the current tenant.

| Parameter | Type | Required | Description   |
| --------- | ---- | -------- | ------------- |
| —         | —    | —        | No parameters |

**Permission:** Authenticated only — visible to any caller with an active context. The server returns only the workspaces the caller actually has access to.

```json title="Example tool call" theme={"system"}
{
  "name": "dome_workspaces_list"
}
```

## Workspaces Create

`dome_workspaces_create`

Create a new workspace in the current tenant. The server auto-generates a URL-safe slug from the display name.

| Parameter | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `name`    | string | Yes      | Workspace display name |

**Permission:** Tenant-level `tenant.manage` (held by tenant `admin`, or by org `owner` / `admin` via cascade). Workspace-only roles cannot create workspaces.

```json title="Example tool call" theme={"system"}
{
  "name": "dome_workspaces_create",
  "arguments": {
    "name": "staging"
  }
}
```

## Workspaces Get

`dome_workspaces_get`

Get a single workspace in the current tenant. Accepts a UUID or a slug; defaults to the active workspace when omitted.

| Parameter   | Type   | Required | Description                                                    |
| ----------- | ------ | -------- | -------------------------------------------------------------- |
| `workspace` | string | No       | Workspace ID (UUID) or slug. Defaults to the active workspace. |

**Permission:** Authenticated only — visible to any caller with an active context. The server enforces that the caller can read the requested workspace.

## Workspaces Delete

`dome_workspaces_delete`

Delete a workspace from the current tenant. Accepts a UUID or a slug. Marked destructive.

| Parameter   | Type   | Required | Description                 |
| ----------- | ------ | -------- | --------------------------- |
| `workspace` | string | Yes      | Workspace ID (UUID) or slug |

**Permission:** `workspace.manage`

<Warning>
  Workspace deletion is permanent and cannot be undone.
</Warning>

## Provision Sandbox

`dome_provision_sandbox`

Provision a sandbox environment for development and testing. Use `scope="tenant"` to create an isolated sandbox tenant with workspace and API key (requires org admin/owner). Use `scope="workspace"` to create a sandbox workspace in the current tenant (requires tenant admin/operator/security).

| Parameter        | Type   | Required | Description                                                                                                                                        |
| ---------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scope`          | string | Yes      | `tenant` or `workspace`                                                                                                                            |
| `tenant_name`    | string | No       | Sandbox tenant name suffix (auto-generated if omitted). Used only when `scope="tenant"`. Must be lowercase alphanumeric and hyphens, max 64 chars. |
| `workspace_name` | string | No       | Sandbox workspace name suffix (auto-generated if omitted). Used with both scopes.                                                                  |

**Permission:** Tenant-level `sandbox.workspace.create` for `scope="workspace"` (held by every tenant role, plus org `owner` / `admin` via cascade). Org-level `sandbox.tenant.create` for `scope="tenant"` (held by org `owner` / `admin` only).

```json title="Example — sandbox workspace" theme={"system"}
{
  "name": "dome_provision_sandbox",
  "arguments": {
    "scope": "workspace",
    "workspace_name": "integration-testing"
  }
}
```

## Act-As Enforcement

Act-as enforcement controls whether agents must present verified end-user identity on every request.

### Workspace Actas Get

`dome_workspace_actas_get`

Get the current act-as enforcement policy for the active workspace.

| Parameter | Type | Required | Description   |
| --------- | ---- | -------- | ------------- |
| —         | —    | —        | No parameters |

**Permission:** `config.manage`

Returns whether act-as is required and which verification methods are allowed.

### Workspace Actas Update

`dome_workspace_actas_update`

Update the act-as enforcement policy for the active workspace.

| Parameter               | Type  | Required | Description                                                                  |
| ----------------------- | ----- | -------- | ---------------------------------------------------------------------------- |
| `actas_required`        | bool  | No       | Require act-as header on all requests                                        |
| `actas_allowed_methods` | array | No       | Allowed verification methods (e.g., `["oidc", "hmac"]`). Empty = any method. |

**Permission:** `config.manage`

```json title="Example tool call" theme={"system"}
{
  "name": "dome_workspace_actas_update",
  "arguments": {
    "actas_required": true,
    "actas_allowed_methods": ["oidc"]
  }
}
```

<Warning>
  Enabling act-as enforcement affects all agents in the workspace. Agents without a configured act-as method are rejected.
</Warning>

## Policy Freshness Window

Each workspace has a configurable freshness window that bounds how long the gateway may serve cached authorization policy before failing closed. Default is 90 seconds; range is 30–86400 seconds. Enforcement is per-workspace — one workspace failing closed does not affect others.

### `dome_workspace_set_freshness_window`

Set the freshness window for the active workspace.

| Parameter | Type   | Required | Description                            |
| --------- | ------ | -------- | -------------------------------------- |
| `seconds` | number | Yes      | Freshness window in seconds (30–86400) |

**Permission:** `config.manage`

```json title="Example tool call" theme={"system"}
{
  "name": "dome_workspace_set_freshness_window",
  "arguments": {
    "seconds": 120
  }
}
```

<Warning>
  Once the window elapses, the gateway denies every request in the workspace and emits a `authorization.staleness_rejected` audit event until the workspace's policy is fresh again.
</Warning>

## Members

### Workspace Members List

`dome_workspace_members_list`

List all members of the active workspace with their roles.

| Parameter | Type | Required | Description   |
| --------- | ---- | -------- | ------------- |
| —         | —    | —        | No parameters |

**Permission:** `workspace.manage`

Returns each member with their email, role, and join date.

### Workspace Members Set

`dome_workspace_members_set`

Grant or update a user's role in the active workspace.

| Parameter    | Type   | Required | Description                                     |
| ------------ | ------ | -------- | ----------------------------------------------- |
| `user_email` | string | Yes      | User email address                              |
| `role`       | string | Yes      | Role: `admin`, `operator`, `security`, `viewer` |

**Permission:** `workspace.manage`

```json title="Example tool call" theme={"system"}
{
  "name": "dome_workspace_members_set",
  "arguments": {
    "user_email": "alice@example.com",
    "role": "operator"
  }
}
```

### Workspace Members Remove

`dome_workspace_members_remove`

Remove a user from the active workspace. Optionally revoke their API keys at the same time by passing `revoke_key_ids` (specific IDs) or `revoke_all_keys=true`. If neither is passed and the user has active keys, the response lists them so the caller can decide which to revoke. Marked destructive.

| Parameter         | Type   | Required | Description                                                                             |
| ----------------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `user_email`      | string | Yes      | User email address                                                                      |
| `revoke_key_ids`  | array  | No       | API key IDs to revoke alongside the removal. Mutually exclusive with `revoke_all_keys`. |
| `revoke_all_keys` | bool   | No       | Revoke all API keys created by the user. Mutually exclusive with `revoke_key_ids`.      |

**Permission:** `workspace.manage`

## Next steps

Tenancy and membership how-tos live under Manage:

* [Prepare Environments](/manage/environments)
* [Manage Access](/manage/access)
* [Scopes](/concepts/platform/scopes) concept