# Disable a registered app

> The apps.disable operation: POST /api/v1/apps/{id}/disable in the REST API and the apps_disable tool in the MCP server.

Disables an app for good, in every organization at once, in one transaction:

- every access and refresh token, authorization code and grant it holds is deleted, and so are the tokens of
  the agents it owns;
- every installation that isn't uninstalled is paused (`pausedReason: app_disabled`, whatever it was before);
  it never resumes (`app_installations.resume` answers `oauth_client_disabled`), and it can still be uninstalled;
- from then on the OAuth server issues the app and its agents nothing and refuses their tokens, and nothing
  installs it.

Your organization and every organization with the app installed get the `APP_DISABLED` alert (high: their
owners and admins are emailed); other organizations aren't told who disabled it. Nothing re-enables an app:
register a new one instead. Disabling a disabled app changes nothing.

## At a glance

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

## Examples

### Disable an app

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

Response (`200`):

```json
{
  "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": "disabled",
  "suspension": null,
  "createdAt": "2026-10-25T09:00:00.000Z",
  "updatedAt": "2026-10-26T14:30:00.000Z"
}
```

## Errors

| Code                                                                                     | HTTP status | When                                                                   | What to do                                                                                           |
| ---------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#version_conflict)     | 409         | The app or one of its installations changed at the same moment; retry. | Fetch the object again and retry the change.                                                         |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#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.                      |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`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).