Agents tools · Ownrecord docs

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 · 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: limit or starting_after is invalid.
resource_not_found: No agent with this ID exists in the organization.
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 · 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: A field is invalid, e.g. a scope the role can't use, or private_key_jwt without public keys.
agent_role_invalid: The role is org_owner, or isn't allowed at the scope's type.
agent_delegation_not_allowed: The agent would get a permission (or live access) you don't have at its scope.
resource_not_found: The scope's entity or brand doesn't exist in the organization.
permission_denied: You can't manage agents, or you aren't a person or an org management key.
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 · 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: No agent with this ID exists in the organization.
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 · 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: A filter or pagination value is invalid.
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 · 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: The agent is revoked.
resource_not_found: No agent with this ID exists in the organization.
version_conflict: The agent changed at the same moment; retry.
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 · 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: The agent is revoked.
resource_not_found: No agent with this ID exists in the organization.
version_conflict: The agent changed at the same moment; retry.
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 · 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: No agent with this ID exists in the organization.
version_conflict: The agent changed at the same moment; retry.
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 · 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: The agent authenticates with private_key_jwt and has no secret.
agent_revoked: The agent is revoked.
resource_not_found: No agent with this ID exists in the organization.
version_conflict: The agent changed at the same moment; retry.
permission_denied: You can't manage agents.
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 · 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: 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: The role is org_owner, or isn't allowed at the scope's type.
agent_delegation_not_allowed: The agent would get a permission (or live access) you don't have at its scope.
agent_revoked: The agent is revoked.
resource_not_found: No such agent, or the scope's entity or brand doesn't exist.
version_conflict: The agent changed at the same moment; retry.
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
}

agents_activity#

Arguments#

Errors#

Example#

agents_create#

Arguments#

Errors#

Examples#

agents_get#

Arguments#

Errors#

Example#

agents_list#

Arguments#

Errors#

Examples#

agents_pause#

Arguments#

Errors#

Example#

agents_resume#

Arguments#

Errors#

Example#

agents_revoke#

Arguments#

Errors#

Example#

agents_rotate_secret#

Arguments#

Errors#

Example#

agents_update#

Arguments#

Errors#

Examples#

`agents_activity`

Arguments

Errors

Example

`agents_create`

Arguments

Errors

Examples

`agents_get`

Arguments

Errors

Example

`agents_list`

Arguments

Errors

Examples

`agents_pause`

Arguments

Errors

Example

`agents_resume`

Arguments

Errors

Example

`agents_revoke`

Arguments

Errors

Example

`agents_rotate_secret`

Arguments

Errors

Example

`agents_update`

Arguments

Errors

Examples