# Agents tools

> MCP tools for Agents: agents_activity, agents_create, agents_get, agents_list, agents_pause, agents_resume, agents_revoke, agents_rotate_secret, agents_update.

- `agents_activity`: List an agent's activity
- `agents_create`: Create an org agent
- `agents_get`: Get an org agent
- `agents_list`: List org agents
- `agents_pause`: Pause an org agent
- `agents_resume`: Resume a paused org agent
- `agents_revoke`: Revoke an org agent
- `agents_rotate_secret`: Rotate an org agent's client secret
- `agents_update`: Update an org agent

## `agents_activity`

**List an agent's activity.** Operation [`agents.activity`](https://ownrecord.io/docs/reference/agents-activity.md) · Organization level · permission `audit:read` · risk tier `read` · since M10

The agent's activity feed, newest first, from the audit log: every change it made (`outcome: "succeeded"`),
every call that asked for approval instead of running (`approval_requested`, with the approval's current
`status`), and every run a person approved (`ran_after_approval`), each with the operation, its target, the mode,
the entity or brand, the surface (`via`) and the OAuth client it came through. Reads aren't in the audit log, so
they aren't listed. Both modes are listed; `usage` is today's use (UTC) of its daily limits in the request's
mode. Paginate with `limit` (1–100, default 10) and `starting_after`.

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument         | Type         | Required | Description |
| ---------------- | ------------ | -------- | ----------- |
| `id`             | ID (`agt_…`) | yes      | –           |
| `limit`          | integer      | no       | (1–100)     |
| `starting_after` | ID (`aud_…`) | no       | –           |

- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): `limit` or `starting_after` is invalid.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No agent with this ID exists in the organization.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't read the organization's audit log.

### Example

**A refund above the daily limit, approved and run**

Arguments:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8"
}
```

Result `output`:

```json
{
  "object": "list",
  "data": [
    {
      "object": "activity_entry",
      "livemode": false,
      "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
      "brandId": "brd_01m4ttwd3veh9apbewxheq5xh5",
      "via": "mcp",
      "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
      "onBehalfOfUserId": null,
      "appInstallationId": null,
      "id": "aud_01m4ttwd3veh9apbewxheq5xhh",
      "at": "2026-10-26T15:02:11.000Z",
      "action": "refunds.create",
      "operationId": "refunds.create",
      "target": "re_01m4ttwd3veh9apbewxheq5xhj",
      "outcome": "ran_after_approval",
      "approval": {
        "id": "apr_01m4ttwd3veh9apbewxheq5xhk",
        "status": "executed",
        "approvedBy": ["usr_01m4ttwd3veh9apbewxheq5xh7"]
      }
    },
    {
      "object": "activity_entry",
      "livemode": false,
      "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
      "brandId": "brd_01m4ttwd3veh9apbewxheq5xh5",
      "via": "mcp",
      "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
      "onBehalfOfUserId": null,
      "appInstallationId": null,
      "id": "aud_01m4ttwd3veh9apbewxheq5xhf",
      "at": "2026-10-26T14:30:00.000Z",
      "action": "approvals.request",
      "operationId": "refunds.create",
      "target": "apr_01m4ttwd3veh9apbewxheq5xhk",
      "outcome": "approval_requested",
      "approval": {
        "id": "apr_01m4ttwd3veh9apbewxheq5xhk",
        "status": "executed",
        "approvedBy": ["usr_01m4ttwd3veh9apbewxheq5xh7"]
      }
    },
    {
      "object": "activity_entry",
      "livemode": false,
      "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
      "brandId": "brd_01m4ttwd3veh9apbewxheq5xh5",
      "via": "mcp",
      "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
      "onBehalfOfUserId": null,
      "appInstallationId": null,
      "id": "aud_01m4ttwd3veh9apbewxheq5xhg",
      "at": "2026-10-26T14:10:00.000Z",
      "action": "refunds.create",
      "operationId": "refunds.create",
      "target": "re_01m4ttwd3veh9apbewxheq5xhm",
      "outcome": "succeeded",
      "approval": null
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "usage": {
    "day": "2026-10-26",
    "livemode": false,
    "mutations": 2,
    "amounts": [
      {
        "operationId": "refunds.create",
        "amount": {
          "amount": "450000000",
          "currency": "EUR"
        }
      }
    ]
  }
}
```

## `agents_create`

**Create an org agent.** Operation [`agents.create`](https://ownrecord.io/docs/reference/agents-create.md) · Organization level · permission `agents:admin` · risk tier `security` · since M10

Creates an agent: a machine identity for the organization's own AI agents and automations. It holds one
`role` at a `scope` (the organization, one legal entity or one brand), like a member, and gets access tokens
with OAuth 2.1 `client_credentials` at `/oauth/token`.

- `authMethod: "client_secret_basic"` (default): the response contains the client secret in
  `credentials.clientSecret`. **It is shown only once**; only a hash is stored.
- `authMethod: "private_key_jwt"`: give your public keys in `jwks`; the agent signs a client assertion
  instead of sending a secret.

`scopes` are the permission scopes its tokens may carry (default: everything the role can use at that scope).
An agent is **test mode only** until `livemodeAccess` is turned on, whatever its role. It never gets more than
you have yourself at its scope and mode (`agent_delegation_not_allowed`), never `org_owner`, and never decides
approval requests. `limits` (requests per second, mutations per day, amounts per financial operation) and
`toolSets` (the MCP tool sets it sees: `workflows`, `registry` or operation areas such as `tasks`; none
means all of them) are applied by the runtime.

`dpopBoundAccessTokens: true` makes every token sender-constrained: the token endpoint refuses a request
without a `DPoP` proof (`invalid_grant`), so a leaked token is useless without the agent's private key.

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: false` · `openWorldHint: false`

### Arguments

| Argument                | Type                                                                                            | Required | Description                                                                                                                                                                                              |
| ----------------------- | ----------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                  | string                                                                                          | yes      | (1–100 characters)                                                                                                                                                                                       |
| `description`           | string                                                                                          | no       | (1–500 characters)                                                                                                                                                                                       |
| `contact`               | string                                                                                          | no       | (1–500 characters)                                                                                                                                                                                       |
| `vendor`                | string                                                                                          | no       | (1–500 characters)                                                                                                                                                                                       |
| `role`                  | one of `org_admin`, `billing_admin`, `finance`, `tax_manager`, `support`, `developer`, `viewer` | yes      | –                                                                                                                                                                                                        |
| `scope`                 | object or object or object                                                                      | no       | (default `{"type":"org"}`)                                                                                                                                                                               |
| `livemodeAccess`        | boolean                                                                                         | no       | (default `false`)                                                                                                                                                                                        |
| `scopes`                | array of one of 84 values, e.g. `org:read`, `org:write`, `org:admin`                            | no       | (1–200 items)                                                                                                                                                                                            |
| `authMethod`            | one of `client_secret_basic`, `private_key_jwt`                                                 | no       | (default `"client_secret_basic"`)                                                                                                                                                                        |
| `jwks`                  | object                                                                                          | no       | –                                                                                                                                                                                                        |
| `dpopBoundAccessTokens` | boolean                                                                                         | no       | Require DPoP for every token: a token request without a DPoP proof is refused (RFC 9449). (default `false`)                                                                                              |
| `limits`                | object                                                                                          | no       | –                                                                                                                                                                                                        |
| `toolSets`              | array of string                                                                                 | no       | (at most 20 items)                                                                                                                                                                                       |
| `idempotency_key`       | string                                                                                          | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`               | boolean                                                                                         | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A field is invalid, e.g. a scope the role can't use, or private_key_jwt without public keys.
- [`agent_role_invalid`](https://ownrecord.io/docs/reference/errors.md#agent_role_invalid): The role is org_owner, or isn't allowed at the scope's type.
- [`agent_delegation_not_allowed`](https://ownrecord.io/docs/reference/errors.md#agent_delegation_not_allowed): The agent would get a permission (or live access) you don't have at its scope.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): The scope's entity or brand doesn't exist in the organization.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't manage agents, or you aren't a person or an org management key.
- [`fresh_auth_required`](https://ownrecord.io/docs/reference/errors.md#fresh_auth_required): Your last sign-in is older than 15 minutes.

### Examples

**A bookkeeping agent with a client secret**

Arguments:

```json
{
  "name": "Bookkeeper",
  "description": "Prepares and files the quarterly OSS return",
  "contact": "ops@acme.example",
  "vendor": "In-house, Claude via the MCP server",
  "role": "finance",
  "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"],
  "limits": {
    "amountLimits": [
      {
        "operationId": "refunds.create",
        "perDay": {
          "amount": "200000000",
          "currency": "EUR"
        }
      }
    ]
  },
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "agent": {
    "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
    "object": "agent",
    "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
    "name": "Bookkeeper",
    "description": "Prepares and files the quarterly OSS return",
    "contact": "ops@acme.example",
    "vendor": "In-house, Claude via the MCP server",
    "ownerType": "org",
    "appInstallationId": null,
    "role": "finance",
    "scope": {
      "type": "org"
    },
    "livemodeAccess": false,
    "limits": {
      "rps": null,
      "mutationsPerDay": null,
      "amountLimits": [
        {
          "operationId": "refunds.create",
          "perCall": null,
          "perDay": {
            "amount": "200000000",
            "currency": "EUR"
          }
        }
      ]
    },
    "toolSets": [],
    "status": "active",
    "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
    "authMethod": "client_secret_basic",
    "secretPrefix": "or_cs_Exampl",
    "dpopBoundAccessTokens": false,
    "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"],
    "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
    "createdAt": "2026-10-25T09:00:00.000Z",
    "updatedAt": "2026-10-25T09:00:00.000Z",
    "pausedAt": null,
    "revokedAt": null
  },
  "credentials": {
    "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
    "clientSecret": "or_cs_ExampleOnlyNotARealSecret0000000000000000",
    "tokenEndpoint": "https://ownrecord.io/oauth/token",
    "authMethod": "client_secret_basic"
  }
}
```

**An agent for one brand with a private key JWT**

Arguments:

```json
{
  "name": "Support triage",
  "role": "support",
  "scope": {
    "type": "brand",
    "brandId": "brd_01m4ttwd3veh9apbewxheq5xh5"
  },
  "authMethod": "private_key_jwt",
  "jwks": {
    "keys": [
      {
        "kty": "EC",
        "crv": "P-256",
        "kid": "triage-1",
        "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
        "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
      }
    ]
  },
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "agent": {
    "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
    "object": "agent",
    "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
    "name": "Support triage",
    "description": null,
    "contact": null,
    "vendor": null,
    "ownerType": "org",
    "appInstallationId": null,
    "role": "support",
    "scope": {
      "type": "brand",
      "brandId": "brd_01m4ttwd3veh9apbewxheq5xh5"
    },
    "livemodeAccess": false,
    "limits": {
      "rps": null,
      "mutationsPerDay": null,
      "amountLimits": []
    },
    "toolSets": [],
    "status": "active",
    "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
    "authMethod": "private_key_jwt",
    "secretPrefix": null,
    "dpopBoundAccessTokens": false,
    "scopes": ["customers:read", "customers:write"],
    "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
    "createdAt": "2026-10-25T09:00:00.000Z",
    "updatedAt": "2026-10-25T09:00:00.000Z",
    "pausedAt": null,
    "revokedAt": null
  },
  "credentials": {
    "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
    "clientSecret": null,
    "tokenEndpoint": "https://ownrecord.io/oauth/token",
    "authMethod": "private_key_jwt"
  }
}
```

## `agents_get`

**Get an org agent.** Operation [`agents.get`](https://ownrecord.io/docs/reference/agents-get.md) · Organization level · permission `agents:read` · risk tier `read` · since M10

Returns one agent: role and scope, live access, token scopes, limits, tool sets, status and its OAuth `clientId`. Never the secret.

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument | Type         | Required | Description |
| -------- | ------------ | -------- | ----------- |
| `id`     | ID (`agt_…`) | yes      | –           |

- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No agent with this ID exists in the organization.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see the organization's agents.

### Example

**An agent**

Arguments:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8"
}
```

Result `output`:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
  "object": "agent",
  "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
  "name": "Bookkeeper",
  "description": "Prepares and files the quarterly OSS return",
  "contact": "ops@acme.example",
  "vendor": "In-house, Claude via the MCP server",
  "ownerType": "org",
  "appInstallationId": null,
  "role": "finance",
  "scope": {
    "type": "org"
  },
  "livemodeAccess": false,
  "limits": {
    "rps": null,
    "mutationsPerDay": null,
    "amountLimits": [
      {
        "operationId": "refunds.create",
        "perCall": null,
        "perDay": {
          "amount": "200000000",
          "currency": "EUR"
        }
      }
    ]
  },
  "toolSets": [],
  "status": "active",
  "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
  "authMethod": "client_secret_basic",
  "secretPrefix": "or_cs_Exampl",
  "dpopBoundAccessTokens": false,
  "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"],
  "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
  "createdAt": "2026-10-25T09:00:00.000Z",
  "updatedAt": "2026-10-25T09:00:00.000Z",
  "pausedAt": null,
  "revokedAt": null
}
```

## `agents_list`

**List org agents.** Operation [`agents.list`](https://ownrecord.io/docs/reference/agents-list.md) · Organization level · permission `agents:read` · risk tier `read` · since M10

Lists the organization's agents, newest first, with their role, scope, live access, limits, tool sets and
status. Never returns secrets: an agent's secret is recognised by `secretPrefix`. Filter by `status`;
paginate with `limit` (1–100, default 10) and `starting_after`.

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument         | Type                                 | Required | Description |
| ---------------- | ------------------------------------ | -------- | ----------- |
| `limit`          | integer                              | no       | (1–100)     |
| `starting_after` | ID (`agt_…`)                         | no       | –           |
| `status`         | one of `active`, `paused`, `revoked` | no       | –           |

- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A filter or pagination value is invalid.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see the organization's agents.

### Examples

**Active agents**

Arguments:

```json
{
  "status": "active"
}
```

Result `output`:

```json
{
  "object": "list",
  "data": [
    {
      "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
      "object": "agent",
      "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
      "name": "Bookkeeper",
      "description": "Prepares and files the quarterly OSS return",
      "contact": "ops@acme.example",
      "vendor": "In-house, Claude via the MCP server",
      "ownerType": "org",
      "appInstallationId": null,
      "role": "finance",
      "scope": {
        "type": "org"
      },
      "livemodeAccess": false,
      "limits": {
        "rps": null,
        "mutationsPerDay": null,
        "amountLimits": [
          {
            "operationId": "refunds.create",
            "perCall": null,
            "perDay": {
              "amount": "200000000",
              "currency": "EUR"
            }
          }
        ]
      },
      "toolSets": [],
      "status": "active",
      "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
      "authMethod": "client_secret_basic",
      "secretPrefix": "or_cs_Exampl",
      "dpopBoundAccessTokens": false,
      "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"],
      "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
      "createdAt": "2026-10-25T09:00:00.000Z",
      "updatedAt": "2026-10-25T09:00:00.000Z",
      "pausedAt": null,
      "revokedAt": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

**One agent per page**

Arguments:

```json
{
  "limit": 1
}
```

Result `output`:

```json
{
  "object": "list",
  "data": [
    {
      "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
      "object": "agent",
      "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
      "name": "Bookkeeper",
      "description": "Prepares and files the quarterly OSS return",
      "contact": "ops@acme.example",
      "vendor": "In-house, Claude via the MCP server",
      "ownerType": "org",
      "appInstallationId": null,
      "role": "finance",
      "scope": {
        "type": "org"
      },
      "livemodeAccess": false,
      "limits": {
        "rps": null,
        "mutationsPerDay": null,
        "amountLimits": [
          {
            "operationId": "refunds.create",
            "perCall": null,
            "perDay": {
              "amount": "200000000",
              "currency": "EUR"
            }
          }
        ]
      },
      "toolSets": [],
      "status": "active",
      "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
      "authMethod": "client_secret_basic",
      "secretPrefix": "or_cs_Exampl",
      "dpopBoundAccessTokens": false,
      "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"],
      "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
      "createdAt": "2026-10-25T09:00:00.000Z",
      "updatedAt": "2026-10-25T09:00:00.000Z",
      "pausedAt": null,
      "revokedAt": null
    }
  ],
  "has_more": true,
  "next_cursor": "agt_01m4ttwd3veh9apbewxheq5xh8"
}
```

## `agents_pause`

**Pause an org agent.** Operation [`agents.pause`](https://ownrecord.io/docs/reference/agents-pause.md) · Organization level · permission `agents:admin` · risk tier `security` · since M10

Pauses an agent: **every access token it holds is revoked at once**, and it can't get new ones until it is
resumed (`agents.resume`). Its credentials stay valid for after the resume. Pausing a paused agent changes
nothing; a revoked agent can't be paused.

Annotations: `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument          | Type         | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`agt_…`) | yes      | –                                                                                                                                                                                                        |
| `idempotency_key` | string       | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean      | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`agent_revoked`](https://ownrecord.io/docs/reference/errors.md#agent_revoked): The agent is revoked.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No agent with this ID exists in the organization.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The agent changed at the same moment; retry.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't manage agents.

### Example

**Pause an agent**

Arguments:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
  "object": "agent",
  "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
  "name": "Bookkeeper",
  "description": "Prepares and files the quarterly OSS return",
  "contact": "ops@acme.example",
  "vendor": "In-house, Claude via the MCP server",
  "ownerType": "org",
  "appInstallationId": null,
  "role": "finance",
  "scope": {
    "type": "org"
  },
  "livemodeAccess": false,
  "limits": {
    "rps": null,
    "mutationsPerDay": null,
    "amountLimits": [
      {
        "operationId": "refunds.create",
        "perCall": null,
        "perDay": {
          "amount": "200000000",
          "currency": "EUR"
        }
      }
    ]
  },
  "toolSets": [],
  "status": "paused",
  "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
  "authMethod": "client_secret_basic",
  "secretPrefix": "or_cs_Exampl",
  "dpopBoundAccessTokens": false,
  "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"],
  "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
  "createdAt": "2026-10-25T09:00:00.000Z",
  "updatedAt": "2026-10-26T14:30:00.000Z",
  "pausedAt": "2026-10-26T14:30:00.000Z",
  "revokedAt": null
}
```

## `agents_resume`

**Resume a paused org agent.** Operation [`agents.resume`](https://ownrecord.io/docs/reference/agents-resume.md) · Organization level · permission `agents:admin` · risk tier `security` · since M10

Resumes a paused agent: it can get access tokens again with its existing credentials. Resuming an active agent changes nothing; a revoked agent can't be resumed.

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument          | Type         | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`agt_…`) | yes      | –                                                                                                                                                                                                        |
| `idempotency_key` | string       | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean      | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`agent_revoked`](https://ownrecord.io/docs/reference/errors.md#agent_revoked): The agent is revoked.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No agent with this ID exists in the organization.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The agent changed at the same moment; retry.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't manage agents.

### Example

**Resume an agent**

Arguments:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
  "object": "agent",
  "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
  "name": "Bookkeeper",
  "description": "Prepares and files the quarterly OSS return",
  "contact": "ops@acme.example",
  "vendor": "In-house, Claude via the MCP server",
  "ownerType": "org",
  "appInstallationId": null,
  "role": "finance",
  "scope": {
    "type": "org"
  },
  "livemodeAccess": false,
  "limits": {
    "rps": null,
    "mutationsPerDay": null,
    "amountLimits": [
      {
        "operationId": "refunds.create",
        "perCall": null,
        "perDay": {
          "amount": "200000000",
          "currency": "EUR"
        }
      }
    ]
  },
  "toolSets": [],
  "status": "active",
  "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
  "authMethod": "client_secret_basic",
  "secretPrefix": "or_cs_Exampl",
  "dpopBoundAccessTokens": false,
  "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"],
  "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
  "createdAt": "2026-10-25T09:00:00.000Z",
  "updatedAt": "2026-10-26T14:30:00.000Z",
  "pausedAt": null,
  "revokedAt": null
}
```

## `agents_revoke`

**Revoke an org agent.** Operation [`agents.revoke`](https://ownrecord.io/docs/reference/agents-revoke.md) · Organization level · permission `agents:admin` · risk tier `security` · since M10

Revokes an agent for good: every access token is revoked at once and its credentials stop working. It stays
listed (with its audit trail) as `revoked`; create a new agent to replace it. Revoking a revoked agent changes
nothing.

Annotations: `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument          | Type         | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`agt_…`) | yes      | –                                                                                                                                                                                                        |
| `idempotency_key` | string       | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean      | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No agent with this ID exists in the organization.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The agent changed at the same moment; retry.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't manage agents.

### Example

**Revoke an agent**

Arguments:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
  "object": "agent",
  "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
  "name": "Bookkeeper",
  "description": "Prepares and files the quarterly OSS return",
  "contact": "ops@acme.example",
  "vendor": "In-house, Claude via the MCP server",
  "ownerType": "org",
  "appInstallationId": null,
  "role": "finance",
  "scope": {
    "type": "org"
  },
  "livemodeAccess": false,
  "limits": {
    "rps": null,
    "mutationsPerDay": null,
    "amountLimits": [
      {
        "operationId": "refunds.create",
        "perCall": null,
        "perDay": {
          "amount": "200000000",
          "currency": "EUR"
        }
      }
    ]
  },
  "toolSets": [],
  "status": "revoked",
  "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
  "authMethod": "client_secret_basic",
  "secretPrefix": "or_cs_Exampl",
  "dpopBoundAccessTokens": false,
  "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"],
  "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
  "createdAt": "2026-10-25T09:00:00.000Z",
  "updatedAt": "2026-10-26T14:30:00.000Z",
  "pausedAt": null,
  "revokedAt": "2026-10-26T14:30:00.000Z"
}
```

## `agents_rotate_secret`

**Rotate an org agent's client secret.** Operation [`agents.rotate_secret`](https://ownrecord.io/docs/reference/agents-rotate-secret.md) · Organization level · permission `agents:admin` · risk tier `security` · since M10

Replaces the agent's client secret. The response contains the new secret in `credentials.clientSecret`, **shown
only once**; the old secret stops working at once. Access tokens already issued keep working until they expire
(15 minutes): pause the agent to revoke them too. Only agents that authenticate with a secret have one;
`private_key_jwt` agents rotate their keys with `agents.update`.

Annotations: `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: false` · `openWorldHint: false`

### Arguments

| Argument          | Type         | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`agt_…`) | yes      | –                                                                                                                                                                                                        |
| `idempotency_key` | string       | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean      | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): The agent authenticates with private_key_jwt and has no secret.
- [`agent_revoked`](https://ownrecord.io/docs/reference/errors.md#agent_revoked): The agent is revoked.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No agent with this ID exists in the organization.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The agent changed at the same moment; retry.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't manage agents.
- [`fresh_auth_required`](https://ownrecord.io/docs/reference/errors.md#fresh_auth_required): Your last sign-in is older than 15 minutes.

### Example

**Rotate a leaked secret**

Arguments:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "agent": {
    "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
    "object": "agent",
    "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
    "name": "Bookkeeper",
    "description": "Prepares and files the quarterly OSS return",
    "contact": "ops@acme.example",
    "vendor": "In-house, Claude via the MCP server",
    "ownerType": "org",
    "appInstallationId": null,
    "role": "finance",
    "scope": {
      "type": "org"
    },
    "livemodeAccess": false,
    "limits": {
      "rps": null,
      "mutationsPerDay": null,
      "amountLimits": [
        {
          "operationId": "refunds.create",
          "perCall": null,
          "perDay": {
            "amount": "200000000",
            "currency": "EUR"
          }
        }
      ]
    },
    "toolSets": [],
    "status": "active",
    "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
    "authMethod": "client_secret_basic",
    "secretPrefix": "or_cs_Exampl",
    "dpopBoundAccessTokens": false,
    "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"],
    "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
    "createdAt": "2026-10-25T09:00:00.000Z",
    "updatedAt": "2026-10-26T14:30:00.000Z",
    "pausedAt": null,
    "revokedAt": null
  },
  "credentials": {
    "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
    "clientSecret": "or_cs_ExampleOnlyNotARealSecret0000000000000000",
    "tokenEndpoint": "https://ownrecord.io/oauth/token",
    "authMethod": "client_secret_basic"
  }
}
```

## `agents_update`

**Update an org agent.** Operation [`agents.update`](https://ownrecord.io/docs/reference/agents-update.md) · Organization level · permission `agents:admin` · risk tier `security` · since M10

Changes an agent's name, description, contact or vendor, its `role` and `scope`, live access
(`livemodeAccess`), token `scopes`, `limits`, `toolSets` or whether every token must be DPoP-bound
(`dpopBoundAccessTokens`: then the token endpoint refuses a request without a `DPoP` proof; tokens already issued
keep working until they expire). Send only what changes; `null` in `limits` clears a value. Changes apply to the
agent's next call: role, scope and live access are read on every call, and its current tokens are narrowed to the
new scopes at once (wider scopes need a new token).

The same rules as creating apply: never `org_owner`, never more than you have yourself at the agent's scope and
mode. A revoked agent can't be changed.

`limits` are enforced on every call (spec §41.4): `rps` operation calls per second (`agent_rate_limited`),
`mutationsPerDay` changes per UTC day and mode (`agent_daily_limit_reached`), and `amountLimits` per financial
operation and currency: a call above `perCall`, or above `perDay` with what the agent already moved today, or
without an amount, **creates an approval request instead of running**. Amount limits apply only to operations
that carry an amount (those an approval policy can limit).

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument                | Type                                                                                            | Required | Description                                                                                                                                                                                              |
| ----------------------- | ----------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | ID (`agt_…`)                                                                                    | yes      | –                                                                                                                                                                                                        |
| `name`                  | string                                                                                          | no       | (1–100 characters)                                                                                                                                                                                       |
| `description`           | string or null                                                                                  | no       | –                                                                                                                                                                                                        |
| `contact`               | string or null                                                                                  | no       | –                                                                                                                                                                                                        |
| `vendor`                | string or null                                                                                  | no       | –                                                                                                                                                                                                        |
| `role`                  | one of `org_admin`, `billing_admin`, `finance`, `tax_manager`, `support`, `developer`, `viewer` | no       | –                                                                                                                                                                                                        |
| `scope`                 | object or object or object                                                                      | no       | –                                                                                                                                                                                                        |
| `livemodeAccess`        | boolean                                                                                         | no       | –                                                                                                                                                                                                        |
| `scopes`                | array of one of 84 values, e.g. `org:read`, `org:write`, `org:admin`                            | no       | (1–200 items)                                                                                                                                                                                            |
| `dpopBoundAccessTokens` | boolean                                                                                         | no       | Require DPoP for every token: a token request without a DPoP proof is refused (RFC 9449).                                                                                                                |
| `limits`                | object                                                                                          | no       | –                                                                                                                                                                                                        |
| `toolSets`              | array of string                                                                                 | no       | (at most 20 items)                                                                                                                                                                                       |
| `idempotency_key`       | string                                                                                          | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`               | boolean                                                                                         | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A field is invalid, e.g. a scope the role can't use, or an amount limit on an operation that moves no amount.
- [`agent_role_invalid`](https://ownrecord.io/docs/reference/errors.md#agent_role_invalid): The role is org_owner, or isn't allowed at the scope's type.
- [`agent_delegation_not_allowed`](https://ownrecord.io/docs/reference/errors.md#agent_delegation_not_allowed): The agent would get a permission (or live access) you don't have at its scope.
- [`agent_revoked`](https://ownrecord.io/docs/reference/errors.md#agent_revoked): The agent is revoked.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No such agent, or the scope's entity or brand doesn't exist.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The agent changed at the same moment; retry.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't manage agents.

### Examples

**Enable live mode**

Arguments:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
  "livemodeAccess": true,
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
  "object": "agent",
  "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
  "name": "Bookkeeper",
  "description": "Prepares and files the quarterly OSS return",
  "contact": "ops@acme.example",
  "vendor": "In-house, Claude via the MCP server",
  "ownerType": "org",
  "appInstallationId": null,
  "role": "finance",
  "scope": {
    "type": "org"
  },
  "livemodeAccess": true,
  "limits": {
    "rps": null,
    "mutationsPerDay": null,
    "amountLimits": [
      {
        "operationId": "refunds.create",
        "perCall": null,
        "perDay": {
          "amount": "200000000",
          "currency": "EUR"
        }
      }
    ]
  },
  "toolSets": [],
  "status": "active",
  "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
  "authMethod": "client_secret_basic",
  "secretPrefix": "or_cs_Exampl",
  "dpopBoundAccessTokens": false,
  "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"],
  "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
  "createdAt": "2026-10-25T09:00:00.000Z",
  "updatedAt": "2026-10-26T14:30:00.000Z",
  "pausedAt": null,
  "revokedAt": null
}
```

**Refunds up to €50 each and €200 a day; above, a person approves**

Arguments:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
  "limits": {
    "amountLimits": [
      {
        "operationId": "refunds.create",
        "perCall": {
          "amount": "50000000",
          "currency": "EUR"
        },
        "perDay": {
          "amount": "200000000",
          "currency": "EUR"
        }
      }
    ]
  },
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
  "object": "agent",
  "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
  "name": "Bookkeeper",
  "description": "Prepares and files the quarterly OSS return",
  "contact": "ops@acme.example",
  "vendor": "In-house, Claude via the MCP server",
  "ownerType": "org",
  "appInstallationId": null,
  "role": "finance",
  "scope": {
    "type": "org"
  },
  "livemodeAccess": false,
  "limits": {
    "rps": null,
    "mutationsPerDay": null,
    "amountLimits": [
      {
        "operationId": "refunds.create",
        "perCall": {
          "amount": "50000000",
          "currency": "EUR"
        },
        "perDay": {
          "amount": "200000000",
          "currency": "EUR"
        }
      }
    ]
  },
  "toolSets": [],
  "status": "active",
  "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
  "authMethod": "client_secret_basic",
  "secretPrefix": "or_cs_Exampl",
  "dpopBoundAccessTokens": false,
  "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"],
  "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
  "createdAt": "2026-10-25T09:00:00.000Z",
  "updatedAt": "2026-10-26T14:30:00.000Z",
  "pausedAt": null,
  "revokedAt": null
}
```

**Require DPoP-bound tokens**

From now on the token endpoint refuses the agent's token requests without a DPoP proof.

Arguments:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
  "dpopBoundAccessTokens": true,
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
  "object": "agent",
  "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
  "name": "Bookkeeper",
  "description": "Prepares and files the quarterly OSS return",
  "contact": "ops@acme.example",
  "vendor": "In-house, Claude via the MCP server",
  "ownerType": "org",
  "appInstallationId": null,
  "role": "finance",
  "scope": {
    "type": "org"
  },
  "livemodeAccess": false,
  "limits": {
    "rps": null,
    "mutationsPerDay": null,
    "amountLimits": [
      {
        "operationId": "refunds.create",
        "perCall": null,
        "perDay": {
          "amount": "200000000",
          "currency": "EUR"
        }
      }
    ]
  },
  "toolSets": [],
  "status": "active",
  "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
  "authMethod": "client_secret_basic",
  "secretPrefix": "or_cs_Exampl",
  "dpopBoundAccessTokens": true,
  "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"],
  "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
  "createdAt": "2026-10-25T09:00:00.000Z",
  "updatedAt": "2026-10-26T14:30:00.000Z",
  "pausedAt": null,
  "revokedAt": null
}
```

**Cap requests and mutations**

Arguments:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
  "limits": {
    "rps": 5,
    "mutationsPerDay": 500
  },
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "agt_01m4ttwd3veh9apbewxheq5xh8",
  "object": "agent",
  "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
  "name": "Bookkeeper",
  "description": "Prepares and files the quarterly OSS return",
  "contact": "ops@acme.example",
  "vendor": "In-house, Claude via the MCP server",
  "ownerType": "org",
  "appInstallationId": null,
  "role": "finance",
  "scope": {
    "type": "org"
  },
  "livemodeAccess": false,
  "limits": {
    "rps": 5,
    "mutationsPerDay": 500,
    "amountLimits": [
      {
        "operationId": "refunds.create",
        "perCall": null,
        "perDay": {
          "amount": "200000000",
          "currency": "EUR"
        }
      }
    ]
  },
  "toolSets": [],
  "status": "active",
  "clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
  "authMethod": "client_secret_basic",
  "secretPrefix": "or_cs_Exampl",
  "dpopBoundAccessTokens": false,
  "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"],
  "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
  "createdAt": "2026-10-25T09:00:00.000Z",
  "updatedAt": "2026-10-26T14:30:00.000Z",
  "pausedAt": null,
  "revokedAt": null
}
```