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

# Delegated agents

> Configure agents that act for a verified person so Rules, Quotas, and audit can authorize on that human

export const delegatedAgent = "A delegated agent acts for a verified person. Dome verifies the end-user identity on each request so Rules, Quotas, and audit can authorize on that human.";

<p>
  {delegatedAgent}
</p>

## Overview

Your application sends the identity on each request as `X-Dome-Act-As`. Dome verifies it, then Rules and audit can read `principal.act_as`. The agent still authenticates as itself. Act-As never replaces agent authentication.

For a request to authorize as a person, three things have to be true:

1. **Dome knows how to verify the person.** You point Dome at an IdP (OIDC) or a shared HMAC secret, either as a workspace verification provider on this page or inline on the agent. You can also set a workspace floor that requires every agent to present verified Act-As and limits which methods are allowed.
2. **The agent is configured to act for people.** On the agent record you set the Act-As method, whether a person is required, which provider to use, and optional allow-lists. Do that when you [register](/connect/agents#register-agent) or [update](/connect/agents#change-end-user-identity) the agent.
3. **Your application sends who the person is.** Each request includes `X-Dome-Act-As`. Without it, Rules have no end user to evaluate. Refer to [Pass identity for delegated agents](/develop#pass-identity-for-delegated-agents).

Unverified headers never become Cedar claims. The agent credential still identifies the workload. Act-as never replaces agent authentication. A verified end user cannot expand access beyond a higher-scope `forbid`.

The typical workflow is:

1. [Create a verification provider](#create-a-verification-provider): [OIDC](#oidc) or [HMAC](#hmac), or inline OIDC/HMAC on the agent.
2. Configure Act-As on the agent when you [register](/connect/agents#register-agent) or [update](/connect/agents#change-end-user-identity) it.
3. Optionally [require verified identity](#require-verified-identity) for every agent in the workspace.
4. Write [claim-aware Rules](#claim-aware-rules) that read `principal.act_as`. Claim names are on the [Rules](/reference/controls/rules#principal-attributes) reference.

### Verification methods

Each agent chooses how Dome verifies the Act-As envelope. Your application must send a matching `X-Dome-Act-As` value on MCP, OpenAI, and Anthropic requests.

| Method  | How Dome verifies                                                               | What your application sends in `X-Dome-Act-As`                 |
| ------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `oidc`  | Verify an end-user JWT through the provider's OpenID Connect discovery metadata | Raw end-user JWT                                               |
| `hmac`  | Verify a signed identity header with a shared secret                            | Signed, timestamped act-as envelope                            |
| `none`  | Act-As headers are not processed (standing identity only)                       | Canonical JSON encoded with standard base64 (development only) |
| `bound` | Server-bound enrollment identity with no client-supplied Act-As                 | No header. The platform supplies the enrolled user             |

Prefer OIDC or bound identity for production traffic. Agents can share a workspace verification provider or use inline OIDC/HMAC credentials on the agent record.

### Identity claims

Verified identity is exposed to Cedar as `principal.act_as`:

| Claim    | Description                        |
| -------- | ---------------------------------- |
| `sub`    | Stable end-user subject identifier |
| `email`  | End-user email                     |
| `roles`  | End-user roles                     |
| `groups` | End-user groups                    |
| `claims` | Additional customer-defined claims |

Attribute types for policy are also on the [Rules](/reference/controls/rules#principal-attributes) reference.

### Workspace floor

The workspace can require Act-As on every request and restrict which verification methods are allowed. That floor applies to every agent in the workspace. Agent settings can be stricter than the floor, but cannot weaken it.

### Where verified identity is consumed

Verified identity can also:

* Scope [Quotas](/govern/quotas) to an Act-As subject
* Forward to upstream tools when a connection uses an Act-As egress header. Refer to [Tools](/connect/resources/tools#change-egress-headers) and [Tools](/reference/resources/tools#egress-headers) reference
* Drive per-user credentials on the [Tools](/reference/resources/tools#upstream-authentication) reference and [Models](/reference/resources/models#credentials) reference
* Drive pool `match_when` conditions on `principal.act_as.*`. Refer to [Pools](/reference/resources/model-pools#pool-resolution) reference

## Requirements

Before you begin, authenticate to Dome and select a workspace.

### Permissions

Workspace Act-As settings and shared verification providers use `config.manage`. Per-agent Act-As configuration uses agent register permissions. Refer to [Agents](/connect/agents#change-end-user-identity).

| Default roles                    | Permission       | Grants                                                                                 |
| -------------------------------- | ---------------- | -------------------------------------------------------------------------------------- |
| `admin`, `operator`              | `config.manage`  | Create, list, or delete verification providers and update workspace Act-As enforcement |
| `admin`, `operator`, `developer` | `agent.register` | Configure Act-As on an agent                                                           |
| `admin`, `operator`, `security`  | `rules.deploy`   | Required with `agent.register` when setting Act-As allow-lists                         |

## Create a verification provider

Create a workspace-scoped verification provider that delegated agents can share. Assign the returned provider ID when registering or updating an agent with `--actas-provider` / `actas_provider_id`. Agents can instead use inline `--actas-oidc-url` or `--actas-hmac-secret` without a shared provider.

The method you pick here must match what your application puts in `X-Dome-Act-As`. Refer to [Verification methods](#verification-methods). How to send the header is on [Pass identity for delegated agents](/develop#pass-identity-for-delegated-agents).

<Callout icon="key">Requires `config.manage`.</Callout>

### OIDC

Use OIDC when end users sign in through an IdP and your application sends their JWT as `X-Dome-Act-As`.

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome workspace verification-providers create \
      --name workforce-oidc \
      --method oidc \
      --oidc-discovery-url https://auth.example.com/.well-known/openid-configuration
    ```

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

  <Tab title="MCP">
    Tool: `dome_verification_providers_create`

    ```json theme={"system"}
    {
      "name": "workforce-oidc",
      "method": "oidc",
      "oidc_discovery_url": "https://auth.example.com/.well-known/openid-configuration"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_verification_providers_create`](/reference/mcp/verification#verification-providers-create)</Callout>
  </Tab>

  <Tab title="API">
    ```http theme={"system"}
    POST /dome.mgmt.v1.Management/CreateVerificationProvider
    Content-Type: application/json

    {
      "workspace_id": "<workspace-uuid>",
      "name": "workforce-oidc",
      "method": "oidc",
      "oidc_discovery_url": "https://auth.example.com/.well-known/openid-configuration"
    }
    ```

    <Callout icon="code">Reference: [`CreateVerificationProvider`](/api/management/create-verification-provider)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Create an OIDC verification provider" theme={"system"}
    Create an OIDC verification provider named "workforce-oidc" using https://auth.example.com/.well-known/openid-configuration.
    ```
  </Tab>
</Tabs>

### HMAC

Use HMAC when a trusted service constructs and signs the Act-As envelope with a shared secret.

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome workspace verification-providers create \
      --name internal-signer \
      --method hmac \
      --hmac-secret <shared-secret>
    ```

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

  <Tab title="MCP">
    Tool: `dome_verification_providers_create`

    ```json theme={"system"}
    {
      "name": "internal-signer",
      "method": "hmac",
      "hmac_secret": "<shared-secret>"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_verification_providers_create`](/reference/mcp/verification#verification-providers-create)</Callout>
  </Tab>

  <Tab title="API">
    ```http theme={"system"}
    POST /dome.mgmt.v1.Management/CreateVerificationProvider
    Content-Type: application/json

    {
      "workspace_id": "<workspace-uuid>",
      "name": "internal-signer",
      "method": "hmac",
      "hmac_secret": "<shared-secret>"
    }
    ```

    <Callout icon="code">Reference: [`CreateVerificationProvider`](/api/management/create-verification-provider)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Create an HMAC verification provider" theme={"system"}
    Create an HMAC verification provider named "internal-signer" with my shared secret.
    ```
  </Tab>
</Tabs>

## List verification providers

List the verification providers in the workspace.

<Callout icon="key">Requires `config.manage`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome workspace verification-providers list
    ```

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

  <Tab title="MCP">
    Tool: `dome_verification_providers_list`

    ```json theme={"system"}
    {
      "name": "dome_verification_providers_list",
      "arguments": {}
    }
    ```

    <Callout icon="cpu">Reference: [`dome_verification_providers_list`](/reference/mcp/verification#verification-providers-list)</Callout>
  </Tab>

  <Tab title="API">
    ```http theme={"system"}
    POST /dome.mgmt.v1.Management/ListVerificationProviders
    Content-Type: application/json

    {
      "workspace_id": "<workspace-uuid>"
    }
    ```

    <Callout icon="code">Reference: [`ListVerificationProviders`](/api/management/list-verification-providers)</Callout>
  </Tab>
</Tabs>

## Delete a verification provider

Delete a verification provider when no agent should use it.

<Callout icon="key">Requires `config.manage`.</Callout>

<Warning>
  Deleting a provider breaks verification for agents that reference it. Move those agents to another provider or remove their provider assignment first.
</Warning>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome workspace verification-providers delete <provider-id>
    ```

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

  <Tab title="MCP">
    Tool: `dome_verification_providers_delete`

    ```json theme={"system"}
    {
      "provider_id": "<provider-id>"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_verification_providers_delete`](/reference/mcp/verification#verification-providers-delete)</Callout>
  </Tab>

  <Tab title="API">
    ```http theme={"system"}
    POST /dome.mgmt.v1.Management/DeleteVerificationProvider
    Content-Type: application/json

    {
      "workspace_id": "<workspace-uuid>",
      "provider_id": "<provider-id>"
    }
    ```

    <Callout icon="code">Reference: [`DeleteVerificationProvider`](/api/management/delete-verification-provider)</Callout>
  </Tab>
</Tabs>

## Require verified identity

Update the workspace Act-As floor so every agent must present a verified end-user identity (every agent in the workspace behaves as a delegated agent at the edge), and optionally restrict which methods are allowed.

When the workspace requires verified Act-As:

* Every request must include a valid identity envelope.
* The verification method must be allowed by the workspace.
* An agent configured with `actas_method=none` is rejected.
* Invalid, expired, malformed, or unverifiable identity fails closed before authorization.

Agent settings can be stricter than the workspace floor, but cannot weaken it. An agent can require Act-As when the workspace does not, or narrow which verified identities it may present by group, email, or subject. Set per-agent options on [Agents](/connect/agents#change-end-user-identity).

<Callout icon="key">Requires `config.manage`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome workspace actas update --required
    ```

    ```bash theme={"system"}
    dome workspace actas update --allowed-methods oidc,hmac
    ```

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

  <Tab title="MCP">
    Tool: `dome_workspace_actas_update`

    ```json theme={"system"}
    {
      "actas_required": true,
      "actas_allowed_methods": ["oidc", "hmac"]
    }
    ```

    <Callout icon="cpu">Reference: [`dome_workspace_actas_update`](/reference/mcp/workspaces#workspace-actas-update)</Callout>
  </Tab>

  <Tab title="API">
    ```http theme={"system"}
    POST /dome.mgmt.v1.Management/UpdateWorkspaceActAs
    Content-Type: application/json

    {
      "workspace_id": "<workspace-uuid>",
      "actas_required": true,
      "actas_allowed_methods": ["oidc", "hmac"]
    }
    ```

    <Callout icon="code">Reference: [`UpdateWorkspaceActAs`](/api/management/update-workspace-act-as)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Require verified identity" theme={"system"}
    Require verified Act-As on every request in this workspace and allow only oidc and hmac.
    ```
  </Tab>
</Tabs>

Read the current floor with `dome workspace actas get`, `dome_workspace_actas_get`, or [`GetWorkspaceActAs`](/api/management/get-workspace-act-as).

## Claim-aware Rules

Rules can require Act-As and test verified claims. When the workspace permits requests without Act-As, a Rule that reads claims should test `principal has act_as` first.

```cedar title="end-user-access.cedar" theme={"system"}
permit(
  principal,
  action == Dome::Action::"mcp:call",
  resource == Dome::MCPTool::"customer-records"
) when {
  principal has act_as &&
  principal.act_as.roles.contains("support")
};

forbid(
  principal,
  action == Dome::Action::"mcp:call",
  resource == Dome::MCPTool::"production-deploy"
) unless {
  principal has act_as &&
  principal.act_as.roles.contains("admin")
};
```

Refer to [Authorize Access](/govern/rules) for the Rule lifecycle, [Rules](/reference/controls/rules#principal-attributes) reference for claim names, and the [authorization model](/concepts/architecture/authorization-model) concept for evaluation.

## Next steps

* [Configure Act-As on an agent](/connect/agents#change-end-user-identity) for method, required flag, provider, and allow-lists
* [Pass identity for delegated agents](/develop#pass-identity-for-delegated-agents) from your application
* [Identity Patterns](/concepts/identity-patterns) concept for when to choose delegated vs standing identity
* [Agent Identity](/concepts/agents/identity#act-as-identity) concept for tokens and act-as on the request path
* [Simulate Rules](/govern/rules/simulate#simulate-with-agent-act-as) with representative Act-As claims before deploy