# Create an org agent > The agents.create operation: POST /api/v1/agents in the REST API and the agents_create tool in the MCP server. 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. ## At a glance - **REST:** `POST /api/v1/agents` - **MCP tool:** `agents_create` - **Operation ID:** `agents.create` - **Scope:** Organization - **Permission:** `agents:admin` - **Risk tier:** `security` - **Dry run:** Supported (send `Ownrecord-Dry-Run: true`) - **Idempotency:** `Idempotency-Key` required - **Modes:** Test and live - **Authentication:** API key with the `agents:admin` scope - **Fresh sign-in:** In the console, a sign-in within the last 15 minutes - **Since:** M10 ## Request ### Body A JSON object (`Content-Type: application/json`): | Field | Type | Required | Description | | ----------------------------------- | -------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------- | | `name` | string | Yes | | | `description` | string | No | | | `contact` | string | No | | | `vendor` | string | No | | | `role` | one of `org_admin`, `billing_admin`, `finance`, `tax_manager`, `support`, `developer`, `viewer` | Yes | | | `scope` | object | No | | | `livemodeAccess` | boolean | No | | | `scopes` | array of one of 84 values, e.g. `org:read`, `org:write`, `org:admin` (all in the OpenAPI document) | No | | | `authMethod` | one of `client_secret_basic`, `private_key_jwt` | No | | | `jwks` | object | No | | | `jwks.keys` | array of object | Yes | | | `jwks.keys[].kty` | one of `RSA`, `EC`, `OKP` | Yes | | | `jwks.keys[].kid` | string | No | | | `jwks.keys[].use` | `"sig"` | No | | | `jwks.keys[].alg` | string | No | | | `dpopBoundAccessTokens` | boolean | No | Require DPoP for every token: a token request without a DPoP proof is refused (RFC 9449). | | `limits` | object | No | | | `limits.rps` | integer (1 to 10000) or null | No | | | `limits.mutationsPerDay` | integer (0 to 10000000) or null | No | | | `limits.amountLimits` | array of object | No | | | `limits.amountLimits[].operationId` | string | Yes | | | `limits.amountLimits[].perCall` | money or null | No | | | `limits.amountLimits[].perDay` | money or null | No | | | `toolSets` | array of string | No | | ## Response `201 Created` with a JSON object: | Field | Type | Description | | ----------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------- | | `agent` | object | | | `agent.id` | `agt_…` ID | | | `agent.object` | `"agent"` | | | `agent.orgId` | `org_…` ID | | | `agent.name` | string | | | `agent.description` | string or null | | | `agent.contact` | string or null | | | `agent.vendor` | string or null | | | `agent.ownerType` | one of `org`, `app` | | | `agent.appInstallationId` | `ains_…` ID or null | | | `agent.role` | one of `org_admin`, `billing_admin`, `finance`, `tax_manager`, `support`, `developer`, `viewer` | | | `agent.scope` | object | | | `agent.livemodeAccess` | boolean | | | `agent.limits` | object | | | `agent.limits.rps` | integer or null | | | `agent.limits.mutationsPerDay` | integer or null | | | `agent.limits.amountLimits` | array of object | | | `agent.limits.amountLimits[].operationId` | string | | | `agent.limits.amountLimits[].perCall` | money or null | | | `agent.limits.amountLimits[].perDay` | money or null | | | `agent.toolSets` | array of string | | | `agent.status` | one of `active`, `paused`, `revoked` | | | `agent.clientId` | `ocl_…` ID | | | `agent.authMethod` | one of `client_secret_basic`, `client_secret_post`, `private_key_jwt` | | | `agent.secretPrefix` | string or null | | | `agent.dpopBoundAccessTokens` | boolean | | | `agent.scopes` | array of one of 84 values, e.g. `org:read`, `org:write`, `org:admin` (all in the OpenAPI document) | | | `agent.createdBy` | string | | | `agent.createdAt` | string | | | `agent.updatedAt` | string | | | `agent.pausedAt` | string or null | | | `agent.revokedAt` | string or null | | | `credentials` | object | | | `credentials.clientId` | `ocl_…` ID | | | `credentials.clientSecret` | string or null | | | `credentials.tokenEndpoint` | string | | | `credentials.authMethod` | one of `none`, `client_secret_basic`, `client_secret_post`, `private_key_jwt` | | ## Examples ### A bookkeeping agent with a client secret ```http POST /api/v1/agents Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/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" } } ] } } ``` Response (`201`): ```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 ```http POST /api/v1/agents Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/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" } ] } } ``` Response (`201`): ```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" } } ``` ## Errors | Code | HTTP status | When | What to do | | ------------------------------------------------------------------------------------------------------------ | ----------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A field is invalid, e.g. a scope the role can't use, or private_key_jwt without public keys. | Fix the fields listed in `details.issues` and send the request again. | | [`agent_role_invalid`](https://ownrecord.io/docs/reference/errors.md#agent_role_invalid) | 400 | The role is org_owner, or isn't allowed at the scope's type. | Choose a role other than org_owner, at a scope the role allows (org, entity or brand; see the role table in the docs). | | [`agent_delegation_not_allowed`](https://ownrecord.io/docs/reference/errors.md#agent_delegation_not_allowed) | 403 | The agent would get a permission (or live access) you don't have at its scope. | Choose a narrower role, scope or token scopes, turn off live mode for the agent, or ask an organization owner to do it. | | [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404 | The scope's entity or brand doesn't exist in the organization. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't manage agents, or you aren't a person or an org management key. | Ask an organization owner or admin for a role or scope that allows this action. | | [`fresh_auth_required`](https://ownrecord.io/docs/reference/errors.md#fresh_auth_required) | 403 | Your last sign-in is older than 15 minutes. | Sign in again, then repeat the action within 15 minutes. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).