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

# Settings

> Set workspace defaults and operational controls

export const settings = "Settings are workspace defaults for audit retention, policy refresh, and agent token lifetime inside an existing workspace.";

<p>
  {settings}
</p>

## Overview

Each workspace carries its own configuration. Unset keys resolve to their defaults. Set only values that differ from the platform baseline, and validate each change against the supported range before rollout.

Configuration writes are audited. Every write emits a `workspace.config.changed` event with previous and new values. Sensitive values use `<redacted>` in the audit payload.

The typical workflow is:

1. [List or set workspace defaults](#configure-workspace-defaults) for the keys you need to change.
2. Optionally tune [token lifetime](#token-lifetime) via `identity.token_ttl` for agent access tokens.
3. [Review changes](#review-changes) in audit before and after a rollout.

The sections below explain the keys you can set and how token lifetime relates to other sessions.

### Workspace configuration keys

These keys control retention, policy sync, bundle history, and agent token lifetime.

| Key                                 | Default | Range      | Effect                                |
| ----------------------------------- | ------- | ---------- | ------------------------------------- |
| `audit.retention_days`              | `90`    | `1`–`3650` | Retains audit events before pruning.  |
| `authorization.rule_sync_interval`  | `30s`   | `5s`–`10m` | Refreshes the gateway policy bundle.  |
| `authorization.max_bundle_versions` | `10`    | `1`–`100`  | Retains policy versions for rollback. |
| `identity.token_ttl`                | `10m`   | `1m`–`24h` | Sets agent access-token lifetime.     |

You list and set these keys when you [configure workspace defaults](#configure-workspace-defaults).

### Token lifetime

`identity.token_ttl` controls tokens returned by `Identity.ExchangeToken`. New exchanges read the current value without restarting services.

Use shorter lifetimes for ephemeral jobs. Increase the value only when refresh overhead justifies the larger exposure window.

Dashboard sessions, credential links, and upstream OAuth tokens use separate lifetimes.

Set the value with the same [configure workspace defaults](#configure-workspace-defaults) operation used for other keys.

## Requirements

Before you begin, authenticate the Dome CLI and select a workspace context.

### Permissions

Workspace settings writes require an `admin` role (or equivalent cascade) with `config.manage`. Each operation states the permission it requires.

For exhaustive flags, tool parameters, and endpoint contracts, refer to the [CLI](/cli/settings/workspace), [MCP](/reference/mcp/workspaces), and [API](/api/management/get-config) references.

| Default roles                             | Permission      | Grants                                    |
| ----------------------------------------- | --------------- | ----------------------------------------- |
| Workspace `admin` (or equivalent cascade) | `config.manage` | List and set workspace configuration keys |

## Configure workspace defaults

List or set [workspace configuration keys](#workspace-configuration-keys). Unset keys resolve to their defaults. Set only values that differ from the platform baseline.

<Callout icon="key">Requires workspace `admin` (or an equivalent cascaded role) with `config.manage`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome workspace config list
    dome workspace config set --key audit.retention_days --value 90
    dome workspace config set --key identity.token_ttl --value 5m
    ```

    <Callout icon="terminal">Reference: [`dome workspace`](/cli/settings/workspace)</Callout>
  </Tab>

  <Tab title="MCP">
    Tools: `dome_workspace_config_list`, `dome_workspace_config_set`

    <Callout icon="cpu">Reference: [`dome_workspace_config_set`](/reference/mcp/workspaces)</Callout>
  </Tab>

  <Tab title="API">
    ```http theme={"system"}
    POST /dome.mgmt.v1.Management/GetWorkspaceConfig
    POST /dome.mgmt.v1.Management/SetWorkspaceConfig
    ```

    <Callout icon="code">Reference: [`GetConfig`](/api/management/get-config)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Configure workspace defaults" theme={"system"}
    List the workspace configuration. Set workspace config key "audit.retention_days" to "90".
    ```
  </Tab>
</Tabs>

Every write emits a `workspace.config.changed` event with previous and new values. Sensitive values use `<redacted>` in the audit payload.

## Review changes

Query configuration changes before and after a rollout.

```bash theme={"system"}
dome audit query \
  --types workspace.config.changed \
  --primary-resource-kind workspace
```

Use [Audit events](/operate/audit) to filter the full configuration history.

## Next steps

* [Manage Access](/manage/access)
* [Prepare Environments](/manage/environments)
* [Audit events](/operate/audit) — filter on `workspace.config.changed`