Rotate a registered app's client secret

Replaces a confidential app's client secret. The new secret is in credentials.clientSecret, shown only once; the old one stops working at once, so update your server first. Tokens already issued keep working.

At a glance

REST: POST /api/v1/apps/{id}/rotate_secret
MCP tool: apps_rotate_secret
Operation ID: apps.rotate_secret
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

Path parameters

Field	Type	Description
`id`	`ocl_…` ID

Body

This operation takes no body.

Response

200 OK with a JSON object:

Field	Type	Description
`app`	object
`app.id`	`ocl_…` ID
`app.object`	`"app"`
`app.ownerOrgId`	`org_…` ID
`app.name`	string
`app.publisher`	string
`app.logoUrl`	string or null
`app.websiteUrl`	string or null
`app.privacyPolicyUrl`	string or null
`app.redirectUris`	array of string
`app.type`	one of `confidential`, `public`
`app.visibility`	one of `private`, `listed`
`app.review`	object
`app.review.status`	one of `not_submitted`, `pending`, `changes_requested`, `approved`, `rejected`
`app.review.at`	string or null
`app.verified`	boolean
`app.scopes`	array of one of 84 values, e.g. `org:read`, `org:write`, `org:admin` (all in the OpenAPI document)
`app.secretPrefix`	string or null
`app.dpopBoundAccessTokens`	boolean
`app.status`	one of `active`, `disabled`
`app.suspension`	object or null
`app.createdAt`	string
`app.updatedAt`	string
`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

Rotate the secret

HTTP

POST /api/v1/apps/ocl_01m4ttwd3veh9apbewxheq5xha/rotate_secret
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14

Response (200):

JSON

{
  "app": {
    "id": "ocl_01m4ttwd3veh9apbewxheq5xha",
    "object": "app",
    "ownerOrgId": "org_01m4ttwd3veh9apbewxheq5xhb",
    "name": "Ledgerly AI",
    "publisher": "Ledgerly AI B.V.",
    "logoUrl": null,
    "websiteUrl": "https://ledgerly.example",
    "privacyPolicyUrl": "https://ledgerly.example/privacy",
    "redirectUris": ["https://ledgerly.example/oauth/callback"],
    "type": "confidential",
    "visibility": "listed",
    "review": {
      "status": "approved",
      "at": "2026-10-25T09:00:00.000Z"
    },
    "verified": true,
    "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write", "ledger:read"],
    "secretPrefix": "or_cs_Exampl",
    "dpopBoundAccessTokens": false,
    "status": "active",
    "suspension": null,
    "createdAt": "2026-10-25T09:00:00.000Z",
    "updatedAt": "2026-10-26T14:30:00.000Z"
  },
  "credentials": {
    "clientId": "ocl_01m4ttwd3veh9apbewxheq5xha",
    "clientSecret": "or_cs_ExampleOnlyNotARealSecret0000000000000000",
    "tokenEndpoint": "https://ownrecord.io/oauth/token",
    "authMethod": "client_secret_basic"
  }
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	The app is public and has no secret.	Fix the fields listed in `details.issues` and send the request again.
`oauth_client_disabled`	409	The app is disabled.	Register a new app, or create a new agent.
`resource_not_found`	404	Your organization registered no app with this ID.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`version_conflict`	409	The app changed at the same moment; retry.	Fetch the object again and retry the change.
`permission_denied`	403	You can't manage the organization's apps.	Ask an organization owner or admin for a role or scope that allows this action.
`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: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Rotate the secret#

Errors#