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

# Agents

> Register agents, issue credentials, allow resources, and manage lifecycle

export const agent = "An agent is an identity in Dome that represents an application, assistant, or automated process making requests. Dome authenticates, authorizes, and audits each agent's calls to tools and models.";

<p>
  {agent}
</p>

Refer to [Agents](/concepts/agents) concept for how agent identity works.

## Overview

Dome separates an agent's identity from its credentials and access. Registering an agent creates a durable identity for the application or process, but does not grant access. An API key lets the runtime authenticate as that identity. Allowed resources, Gateway membership, and [Rules](/govern/rules) determine what requests Dome permits.

Because credentials and access are separate, you can rotate a key without changing permissions or change permissions without issuing a new key.

The typical workflow is:

1. [Register the agent](#register-agent) to create the identity.
2. [Get the agent](#get-agent) to confirm the record and note the workspace gateway endpoint.
3. Allow the [resources](#allowed-resources) it needs.
4. [Create an API key](#create-key) for the runtime.
5. Point the client at Dome. Refer to [Develop](/develop#authenticate).

When access must depend on the person the agent acts for, configure [delegated identity](#delegated-identity). When one agent spawns others, set a [parent](#hierarchy) at register time.

### Allowed resources

An agent reaches only the resources you allow it: model pools, individual models, MCP tools, and Gateways. When an agent allows a Gateway, Dome lets it use that endpoint.

Allowing a resource is shorthand for creating a rule. Each entry generates a rule in the agent's rule bundle which the gateway enforces on the next request without a separate deploy. Because it creates rules, allowing a resource needs `rules.deploy` in addition to the permission to edit the agent, so someone with the developer role can register an agent and change its metadata but cannot change which resources it reaches.

Dome derives the agent's **capabilities** (the strings its rules can test) from the same selections:

| You allow           | Capabilities Dome derives                |
| ------------------- | ---------------------------------------- |
| Model pool or model | `llm:invoke`                             |
| Tool                | `mcp:call`, `mcp:discover`               |
| Gateway             | `llm:invoke`, `mcp:call`, `mcp:discover` |

You set a capability yourself only when one of your rules tests a string Dome would not derive, such as `read-data`. When the shorthand cannot express a condition, such as a time window, a PII field, or an act-as claim, create [Rules](/govern/rules) directly. A generated bundle adds to workspace defaults rather than replacing them.

You can allow resources when you [register an agent](#register-agent) or [change them later](#change-allowed-resources).

### Delegated identity

An agent can act for a person rather than only for itself. When it presents an act-as claim, Dome verifies the claim before authorizing the request, and the audit trail records the end user alongside the agent.

On the agent you choose the verification method (`oidc`, `hmac`, `bound`, or `none`), whether a claim is mandatory on every request, which provider to use, and optional allow-lists by group, email, or subject. An agent with no restrictions accepts any verified identity. Like allowed resources, these settings generate rules, so changing them needs `rules.deploy`.

Workspace providers, the workspace floor, and claim-aware Rules are on [Delegated agents](/connect/agents/delegated). You can configure per-agent settings when you [register](#register-agent) or [update](#change-end-user-identity) the agent.

### Hierarchy

An agent can have a parent. The parent and its descendants form a hierarchy, which helps when one agent spawns or manages others and you want to act on them together. A hierarchy grants no access on its own, and each agent reaches only what you allow it.

A hierarchy can be at most 10 levels deep, and a parent and child must belong to the same tenant. You can set an agent's parent when you [register](#register-agent) it. An update cannot change it afterward. How lifecycle operations reach descendants is under [Manage lifecycle](#manage-lifecycle).

## Requirements

Before you begin:

* Install and authenticate the Dome CLI, then select a workspace context
* Create or select a [Gateway](/connect/gateways), attach the required resources, and grant the agent access

### Permissions

Agent registry, lifecycle, and key operations require platform permissions. Each operation states the permission it requires. For exhaustive flags, tool parameters, and endpoint contracts, refer to the [CLI](/cli/connect/agents), [MCP](/reference/mcp/agents), and [API](/api/agents/register-agent) references.

| Default roles                                | Permission        | Grants                                                                |
| -------------------------------------------- | ----------------- | --------------------------------------------------------------------- |
| All workspace roles                          | `agent.view`      | Get and list agents and keys                                          |
| `admin`, `operator`, `developer`             | `agent.register`  | Register and update agents                                            |
| `admin`, `operator`, `security`, `developer` | `agent.suspend`   | Suspend and reactivate agents                                         |
| `admin`, `operator`, `developer`             | `agent.revoke`    | Revoke agents                                                         |
| `admin`, `operator`                          | `agent.delete`    | Delete agents                                                         |
| `admin`, `operator`, `developer`             | `agentkey.manage` | Create, rotate, or revoke agent keys                                  |
| `admin`, `operator`, `security`              | `rules.deploy`    | Change allowed resources or end-user identity (with `agent.register`) |
| All workspace roles                          | `rules.view`      | View generated rule bundles                                           |

## Register agent

Register an agent to create the record that credentials, allowed resources, and lifecycle operations attach to. You can set [allowed resources](#allowed-resources), [end-user identity](#delegated-identity), and a [parent](#hierarchy) in the same call.

<Callout icon="key">Requires `agent.register`, plus `rules.deploy` if you set allowed resources or end-user identity in the same call.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome agents register \
      --name "data-pipeline-agent"
    ```

    Add `--parent-id` to place the agent in a hierarchy, `--metadata key=value` for your own labels, and `--if-not-exists` to return the existing agent instead of failing when the name is taken.

    <Callout icon="terminal">Reference: [`dome agents register`](/cli/connect/agents#register)</Callout>
  </Tab>

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

    ```json theme={"system"}
    {
      "name": "data-pipeline-agent"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_agents_register`](/reference/mcp/agents#agents-register)</Callout>
  </Tab>

  <Tab title="API">
    ```http theme={"system"}
    POST /dome.agent.v1.AgentRegistry/RegisterAgent HTTP/1.1
    Content-Type: application/json

    {
      "name": "data-pipeline-agent",
      "workspace_id": "{{WORKSPACE_ID}}"
    }
    ```

    <Callout icon="code">Reference: [`RegisterAgent`](/api/agents/register-agent)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Register an agent" theme={"system"}
    Register an agent named "data-pipeline-agent".
    ```
  </Tab>
</Tabs>

```json Response theme={"system"}
{
  "id": "a1b2c3d4-...",
  "name": "data-pipeline-agent",
  "status": "provisioned"
}
```

A new agent starts in `provisioned` and becomes `active` on its first gateway request. Refer to [Manage lifecycle](#manage-lifecycle) for the full state model.

### Register from a file

Register an agent from a YAML or JSON file when a reviewable definition is clearer than a long flag list, such as in CI. The file shape mirrors `RegisterAgentRequest`, the same schema the SDKs and Terraform provider consume, so a misspelled field fails fast instead of dropping silently. The workspace always comes from the active context. A `workspace_id` in the file is ignored.

```yaml agent.yaml theme={"system"}
name: data-pipeline-agent
capabilities: [read]
allowed_pool_names: [openai-prod]
allowed_tools: [github/list_repos]
```

```bash theme={"system"}
dome agents register --file agent.yaml
```

<Callout icon="terminal">Reference: [`dome agents register --file`](/cli/connect/agents#register-from-a-file)</Callout>

## Update agent

Update an agent to change its metadata or capabilities. Only the fields you send change, and list fields replace rather than merge.

<Callout icon="key">Requires `agent.register`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome agents update data-pipeline-agent \
      --metadata environment=production
    ```

    <Callout icon="terminal">Reference: [`dome agents update`](/cli/connect/agents#update)</Callout>
  </Tab>

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

    ```json theme={"system"}
    {
      "agent_id": "data-pipeline-agent",
      "metadata": { "environment": "production" }
    }
    ```

    <Callout icon="cpu">Reference: [`dome_agents_update`](/reference/mcp/agents#agents-update)</Callout>
  </Tab>

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

    {
      "agent_id": "{{AGENT_ID}}",
      "workspace_id": "{{WORKSPACE_ID}}",
      "capabilities": ["read-data", "write-reports"]
    }
    ```

    <Callout icon="code">Reference: [`UpdateAgent`](/api/agents/update-agent)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Update an agent" theme={"system"}
    Update agent "data-pipeline-agent" to add metadata environment=production.
    ```
  </Tab>
</Tabs>

### Change allowed resources

You can change which pools, models, tools, and Gateways the agent may reach. Refer to [Allowed resources](#allowed-resources) for what these grants mean. When you allow models, a pool is usually the better choice than an individual model, because a pool can [fail over and load-balance](/connect/resources/models/pools).

<Callout icon="key">Requires `agent.register` and `rules.deploy`, because every change regenerates the agent's rule bundle.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome agents update data-pipeline-agent \
      --pool "gpt-4-prod" \
      --tool "github/list-issues" \
      --tool "github/create-comment" \
      --gateway "{{GATEWAY_ID}}"
    ```

    Tool names take the form `<connection-name>/<tool-name>`. When a pool is not appropriate, `--model` allows a specific model connection, and `--capabilities` sets custom capability strings.

    <Callout icon="terminal">Reference: [`dome agents update`](/cli/connect/agents#update)</Callout>
  </Tab>

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

    ```json theme={"system"}
    {
      "agent_id": "data-pipeline-agent",
      "allowed_pool_names": ["gpt-4-prod"],
      "allowed_tools": ["github/list-issues", "github/create-comment"]
    }
    ```

    <Callout icon="cpu">Reference: [`dome_agents_update`](/reference/mcp/agents#agents-update)</Callout>
  </Tab>

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

    {
      "agent_id": "{{AGENT_ID}}",
      "workspace_id": "{{WORKSPACE_ID}}",
      "allowed_pool_names": ["gpt-4-prod"],
      "allowed_direct_model_names": [],
      "allowed_tools": ["github/list-issues", "github/create-comment"]
    }
    ```

    <Callout icon="code">Reference: [`UpdateAgent`](/api/agents/update-agent)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Change allowed resources" theme={"system"}
    Restrict agent "data-pipeline-agent" to pool "gpt-4-prod" and tools github/list-issues and github/create-comment.
    ```
  </Tab>
</Tabs>

When you change one of these fields, the value you send replaces the existing list rather than merging into it, so a partial list drops whatever it omits and an empty value clears the list. In the dashboard, the agent detail page hides the edit controls on Capabilities and Delegation when the caller lacks `rules.deploy`, and the edit dialog shows a banner explaining the limit.

### Change end-user identity

You can also change how Dome verifies the end user an agent acts for, and which identities it may present. Refer to [Delegated identity](#delegated-identity) and [Delegated agents](/connect/agents/delegated) for providers and the workspace floor.

<Callout icon="key">Requires `agent.register` and `rules.deploy`.</Callout>

| Setting                         | Flag                                                                        |
| ------------------------------- | --------------------------------------------------------------------------- |
| Verification method             | `--actas-method` (`none`, `oidc`, `hmac`, or `bound`)                       |
| Mandatory claim                 | `--actas-required`                                                          |
| Workspace provider              | `--actas-provider`                                                          |
| Inline OIDC or HMAC credentials | `--actas-oidc-url`, `--actas-hmac-secret`                                   |
| Acceptable identities           | `--actas-allowed-group`, `--actas-allowed-email`, `--actas-allowed-subject` |

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome agents update support-bot \
      --actas-method oidc \
      --actas-required \
      --actas-allowed-group "support-engineers"
    ```

    <Callout icon="terminal">Reference: [`dome agents update`](/cli/connect/agents#update)</Callout>
  </Tab>

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

    ```json theme={"system"}
    {
      "agent_id": "support-bot",
      "actas_method": "oidc",
      "actas_required": true,
      "actas_allowed_groups": ["support-engineers"]
    }
    ```

    <Callout icon="cpu">Reference: [`dome_agents_update`](/reference/mcp/agents#agents-update)</Callout>
  </Tab>

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

    {
      "agent_id": "{{AGENT_ID}}",
      "workspace_id": "{{WORKSPACE_ID}}",
      "actas_method": "oidc",
      "actas_required": true,
      "actas_allowed_groups": ["support-engineers"]
    }
    ```

    <Callout icon="code">Reference: [`UpdateAgent`](/api/agents/update-agent)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Require verified end-user identity" theme={"system"}
    Require OIDC-verified act-as identity on agent "support-bot" and allow only the support-engineers group.
    ```
  </Tab>
</Tabs>

Populating an acceptable-identity list denies any request whose verified claim is not on the list. Leaving all three empty accepts any verified identity, and workspace-level act-as enforcement still applies.

## Get agent

Retrieve an agent by name or UUID. Before you configure a runtime, you should retrieve an agent's information to confirm its status and the endpoint its traffic should reach.

<Callout icon="key">Requires `agent.view`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome agents get data-pipeline-agent
    ```

    <Callout icon="terminal">Reference: [`dome agents get`](/cli/connect/agents#get)</Callout>
  </Tab>

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

    ```json theme={"system"}
    {
      "agent_id": "{{AGENT_ID}}",
      "gateway_id": "{{GATEWAY_ID}}"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_agents_get`](/reference/mcp/agents#agents-get)</Callout>
  </Tab>

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

    {
      "agent_id": "{{AGENT_ID}}",
      "workspace_id": "{{WORKSPACE_ID}}",
      "gateway_id": "{{GATEWAY_ID}}"
    }
    ```

    <Callout icon="code">Reference: [`GetAgent`](/api/agents/get-agent)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Get an agent" theme={"system"}
    Get "data-pipeline-agent" for Gateway "{{GATEWAY_ID}}" and confirm its status and connection endpoints.
    ```
  </Tab>
</Tabs>

When `gateway_id` is supplied, the response includes the agent record and that accessible Gateway's complete protocol endpoints. Omit it for metadata only.

```json Response theme={"system"}
{
  "agent": {
    "id": "a1b2c3d4-…",
    "name": "data-pipeline-agent",
    "status": "active"
  },
  "gateway_id": "{{GATEWAY_ID}}",
  "gateway_endpoints": {
    "gateway_id": "{{GATEWAY_ID}}",
    "gateway_url": "https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}",
    "mcp_url": "https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}/mcp",
    "openai_base_url": "https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}/v1",
    "anthropic_base_url": "https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}"
  }
}
```

The dashboard shows the same pair on the agent detail page's Identity card, each with a copy button.

## List agents

Retrieve a list of agents in a workspace. You can narrow the results by filtering on status, such as to find every suspended agent.

<Callout icon="key">Requires `agent.view`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome agents list --status active
    ```

    A list returns 100 agents unless `--limit` says otherwise.

    <Callout icon="terminal">Reference: [`dome agents list`](/cli/connect/agents#list)</Callout>
  </Tab>

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

    ```json theme={"system"}
    {
      "status": "active",
      "limit": 25
    }
    ```

    `offset` pages through results beyond the limit.

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

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

    {
      "workspace_id": "{{WORKSPACE_ID}}",
      "status": "active"
    }
    ```

    <Callout icon="code">Reference: [`ListAgents`](/api/agents/list-agents)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="List agents" theme={"system"}
    List the active agents in this workspace.
    ```
  </Tab>
</Tabs>

## Manage lifecycle

An agent moves through four states. Provisioned and active agents can send traffic. Suspended and revoked agents are denied.

| State         | Traffic | How it leaves this state                                                       |
| ------------- | ------- | ------------------------------------------------------------------------------ |
| `provisioned` | Allowed | Becomes `active` automatically on the first gateway request                    |
| `active`      | Allowed | An operator [suspends](#suspend) or [revokes](#revoke) it                      |
| `suspended`   | Denied  | An operator [reactivates](#reactivate) or [revokes](#revoke) it                |
| `revoked`     | Denied  | Terminal. You can [delete](#delete) the record, but you cannot undo revocation |

When agents are in a [hierarchy](#hierarchy), lifecycle operations reach descendants differently:

| Operation  | Reach                                                                               |
| ---------- | ----------------------------------------------------------------------------------- |
| Suspend    | The agent alone, or the agent plus its active descendants when you pass `--cascade` |
| Reactivate | The agent alone. Undoing a cascaded suspension takes one call per agent             |
| Revoke     | The agent and every descendant, always, depth-first, any state                      |
| Delete     | The agent alone, or the agent plus its descendants when you request a cascade       |

Parent and child must already share a tenant. Hierarchy does not grant access. Full transition detail is on the [Agent Lifecycle](/concepts/agents/agent-lifecycle) concept.

### Suspend

Suspend an agent to deny its requests until you reactivate it. Suspension is reversible. With cascade, it also suspends active descendants.

<Callout icon="key">Requires `agent.suspend`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome agents suspend data-pipeline-agent --reason "maintenance window"
    ```

    <Callout icon="terminal">Reference: [`dome agents suspend`](/cli/connect/agents#suspend)</Callout>
  </Tab>

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

    ```json theme={"system"}
    {
      "agent_id": "data-pipeline-agent",
      "reason": "maintenance window",
      "cascade": false
    }
    ```

    <Callout icon="cpu">Reference: [`dome_agents_suspend`](/reference/mcp/agents#agents-suspend)</Callout>
  </Tab>

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

    {
      "agent_id": "{{AGENT_ID}}",
      "workspace_id": "{{WORKSPACE_ID}}",
      "reason": "maintenance window"
    }
    ```

    <Callout icon="code">Reference: [`SuspendAgent`](/api/agents/suspend-agent)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Suspend an agent" theme={"system"}
    Suspend agent "data-pipeline-agent" for a maintenance window.
    ```
  </Tab>
</Tabs>

### Reactivate

Reactivate a suspended agent to restore its traffic. Reactivation applies only to an agent in the `suspended` state, and it covers one agent, so a cascaded suspension takes one reactivation per agent.

<Callout icon="key">Requires `agent.suspend`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome agents reactivate data-pipeline-agent
    ```

    <Callout icon="terminal">Reference: [`dome agents reactivate`](/cli/connect/agents#reactivate)</Callout>
  </Tab>

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

    ```json theme={"system"}
    {
      "agent_id": "data-pipeline-agent"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_agents_reactivate`](/reference/mcp/agents#agents-reactivate)</Callout>
  </Tab>

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

    {
      "agent_id": "{{AGENT_ID}}",
      "workspace_id": "{{WORKSPACE_ID}}"
    }
    ```

    <Callout icon="code">Reference: [`ReactivateAgent`](/api/agents/reactivate-agent)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Reactivate an agent" theme={"system"}
    Reactivate agent "data-pipeline-agent".
    ```
  </Tab>
</Tabs>

### Revoke

Revoke an agent to decommission it permanently. Its record and audit history remain readable.

<Callout icon="key">Requires `agent.revoke`.</Callout>

<Warning>
  Revocation cannot be reversed and always cascades to every descendant agent.
</Warning>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome agents revoke data-pipeline-agent --reason "decommissioned"
    ```

    <Callout icon="terminal">Reference: [`dome agents revoke`](/cli/connect/agents#revoke)</Callout>
  </Tab>

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

    ```json theme={"system"}
    {
      "agent_id": "data-pipeline-agent",
      "reason": "decommissioned"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_agents_revoke`](/reference/mcp/agents#agents-revoke)</Callout>
  </Tab>

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

    {
      "agent_id": "{{AGENT_ID}}",
      "workspace_id": "{{WORKSPACE_ID}}",
      "reason": "decommissioned"
    }
    ```

    <Callout icon="code">Reference: [`RevokeAgent`](/api/agents/revoke-agent)</Callout>
  </Tab>
</Tabs>

### Delete

Delete a revoked agent to remove it and all of its data. Deletion works only on a revoked agent and rejects an agent in any other state.

<Callout icon="key">Requires `agent.delete`.</Callout>

<Warning>
  Deletion removes the agent record and its data irreversibly, including its keys. Revoke instead when you need the record retained.
</Warning>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome agents delete data-pipeline-agent --reason "offboarded"
    ```

    Deletion covers one agent, and it fails when that agent still has descendants. Adding `--cascade` deletes the agent and its descendants in one call, deepest first, and every descendant must already be revoked.

    ```bash theme={"system"}
    dome agents delete data-pipeline-agent --cascade
    ```

    <Callout icon="terminal">Reference: [`dome agents delete`](/cli/connect/agents#delete)</Callout>
  </Tab>

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

    ```json theme={"system"}
    {
      "agent_id": "data-pipeline-agent",
      "reason": "offboarded",
      "cascade": false
    }
    ```

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

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

    {
      "agent_id": "{{AGENT_ID}}",
      "workspace_id": "{{WORKSPACE_ID}}",
      "reason": "offboarded"
    }
    ```

    <Callout icon="code">Reference: [`DeleteAgent`](/api/agents/delete-agent)</Callout>
  </Tab>
</Tabs>

## Manage API keys

An API key is the credential the agent runtime presents to Dome. An agent can hold several keys, so you can rotate a credential or keep one key per environment. Keys scope to the agent's tenant and workspace.

<Callout icon="key">Requires `agentkey.manage` to create, rotate, or revoke a key, and `agent.view` to list them.</Callout>

<Warning>
  The token is returned once, when you create or rotate a key. Store it immediately, because it cannot be retrieved again.
</Warning>

### Create key

Create a key to receive the one-time `token`, selected `gateway_id`, and complete `gateway_endpoints`. Supply a Gateway when the agent can access more than one.

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome agents create-key data-pipeline-agent --name "default" --gateway "{{GATEWAY_ID}}"
    ```

    <Callout icon="terminal">Reference: [`dome agents create-key`](/cli/connect/agents#create-key)</Callout>
  </Tab>

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

    ```json theme={"system"}
    {
      "agent": "data-pipeline-agent",
      "name": "default",
      "gateway_id": "{{GATEWAY_ID}}"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_agents_create_key`](/reference/mcp/agents#agents-create-key)</Callout>
  </Tab>

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

    {
      "agent_id": "{{AGENT_ID}}",
      "name": "default",
      "workspace_id": "{{WORKSPACE_ID}}",
      "gateway_id": "{{GATEWAY_ID}}"
    }
    ```

    <Callout icon="code">Reference: [`CreateAgentKey`](/api/agents/create-agent-key)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Create an API key" theme={"system"}
    Create an API key named "default" for agent "data-pipeline-agent" using Gateway "{{GATEWAY_ID}}".
    ```
  </Tab>
</Tabs>

```json Response theme={"system"}
{
  "token": "dome_…",
  "key": { "id": "k_…", "name": "default", "createdAt": "…" },
  "gateway_id": "{{GATEWAY_ID}}",
  "gateway_endpoints": {
    "gateway_id": "{{GATEWAY_ID}}",
    "gateway_url": "https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}",
    "mcp_url": "https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}/mcp",
    "openai_base_url": "https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}/v1",
    "anthropic_base_url": "https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}"
  }
}
```

A separate key for each runtime or environment lets you revoke one without disrupting the others.

### List keys

Retrieve an agent's active keys with their names and creation times. A list never returns tokens, because Dome returns a token only when you create or rotate a key.

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome agents list-keys data-pipeline-agent
    ```

    <Callout icon="terminal">Reference: [`dome agents list-keys`](/cli/connect/agents#list-keys)</Callout>
  </Tab>

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

    ```json theme={"system"}
    {
      "agent": "data-pipeline-agent"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_agents_list_keys`](/reference/mcp/agents#agents-list-keys)</Callout>
  </Tab>

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

    {
      "agent_id": "{{AGENT_ID}}",
      "workspace_id": "{{WORKSPACE_ID}}"
    }
    ```

    <Callout icon="code">Reference: [`ListAgentKeys`](/api/agents/list-agent-keys)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="List an agent's API keys" theme={"system"}
    List the API keys for agent "data-pipeline-agent".
    ```
  </Tab>
</Tabs>

### Rotate key

Rotate a key to revoke the old secret and issue a new one under the same name. Dome returns the new token and the gateway endpoint. The old secret stops authenticating as soon as you rotate, so deploy the new token promptly.

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome agents rotate-key data-pipeline-agent production
    ```

    <Callout icon="terminal">Reference: [`dome agents rotate-key`](/cli/connect/agents#rotate-key)</Callout>
  </Tab>

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

    ```json theme={"system"}
    {
      "agent": "data-pipeline-agent",
      "key_name": "production"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_agents_rotate_key`](/reference/mcp/agents#agents-rotate-key)</Callout>
  </Tab>

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

    {
      "agent_id": "{{AGENT_ID}}",
      "workspace_id": "{{WORKSPACE_ID}}",
      "key_name": "production"
    }
    ```

    <Callout icon="code">Reference: [`RotateAgentKey`](/api/agents/rotate-agent-key)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Rotate an agent key" theme={"system"}
    Rotate the "production" API key for "data-pipeline-agent".
    ```
  </Tab>
</Tabs>

### Revoke key

Revoke a key to retire it without affecting the agent's other keys. A revoked key stops authenticating immediately, so confirm the runtime holds a working key before you revoke this one.

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome agents revoke-key data-pipeline-agent production
    ```

    <Callout icon="terminal">Reference: [`dome agents revoke-key`](/cli/connect/agents#revoke-key)</Callout>
  </Tab>

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

    ```json theme={"system"}
    {
      "agent": "data-pipeline-agent",
      "key_name": "production"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_agents_revoke_key`](/reference/mcp/agents#agents-revoke-key)</Callout>
  </Tab>

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

    {
      "agent_id": "{{AGENT_ID}}",
      "workspace_id": "{{WORKSPACE_ID}}",
      "key_name": "production"
    }
    ```

    <Callout icon="code">Reference: [`RevokeAgentKey`](/api/agents/revoke-agent-key)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Revoke an agent key" theme={"system"}
    Revoke the "production" API key for agent "data-pipeline-agent".
    ```
  </Tab>
</Tabs>

## Manage agent-scoped rules

Agent-scope rules apply to one agent, for conditions [allowed resources](#allowed-resources) cannot express. They evaluate in addition to organization, tenant, and workspace rules, and a deny at the workspace scope overrides an allow at the agent scope. Refer to [Authorize Access](/govern/rules) for creating rules, inherited scopes, and deployment.

### Assign rules

Assign rule files to the agent scope, where the gateway evaluates them alongside the rules the agent inherits from higher scopes.

<Callout icon="key">Requires `rules.deploy`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome agents assign-policy data-pipeline-agent agent-policy.cedar
    ```

    <Callout icon="terminal">Reference: [`dome agents assign-policy`](/cli/connect/agents#assign-policy)</Callout>
  </Tab>

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

    ```json theme={"system"}
    {
      "agent_id": "data-pipeline-agent",
      "files": [
        {
          "name": "agent-policy.cedar",
          "content": "permit(principal, action == Dome::Action::\"mcp:call\", resource == Dome::MCPTool::\"github/list-issues\");"
        }
      ]
    }
    ```

    <Callout icon="cpu">Reference: [`dome_agents_assign_policy`](/reference/mcp/rules#agents-assign-policy)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Assign agent-scoped rules" theme={"system"}
    Assign the rules in agent-policy.cedar to agent "data-pipeline-agent".
    ```
  </Tab>
</Tabs>

### View rules

Retrieve the rules assigned at the agent scope. The result excludes the organization, tenant, and workspace rules the agent also inherits.

<Callout icon="key">Requires `rules.view`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome agents get-policies data-pipeline-agent
    ```

    <Callout icon="terminal">Reference: [`dome agents get-policies`](/cli/connect/agents#get-policies)</Callout>
  </Tab>

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

    ```json theme={"system"}
    {
      "agent_id": "data-pipeline-agent"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_agents_get_policies`](/reference/mcp/rules#agents-get-policies)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="View agent-scoped rules" theme={"system"}
    Show the rules currently assigned to agent "data-pipeline-agent".
    ```
  </Tab>
</Tabs>

## Next steps

* [Delegated agents](/connect/agents/delegated) when access must depend on the person
* [Tools](/connect/resources/tools) and [Models](/connect/resources/models) an agent can call
* [Gateways](/connect/gateways) for membership and grants
* [Develop](/develop#authenticate) to authenticate and route runtime traffic
* [Agent Lifecycle](/concepts/agents/agent-lifecycle) concept for states and cascades