# Narrow an installed app's access > The app_installations.update operation: PATCH /api/v1/app_installations/{id} in the REST API and the app_installations_update tool in the MCP server. Changes what an installed app may do in the organization: fewer `scopes` (only scopes it already has; more need the app to ask for consent again), a different `limitTo` (entities or brands; empty lists = the whole organization), or its `limits`. Changes apply to the app's next call. A revoked installation can't be changed. `limits` work as an agent's (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 (`perCall`, `perDay`; money as integer micros in a string): a call above them, or without an amount, creates an approval request instead of running. Send only what changes; `null` clears a value. ## At a glance - **REST:** `PATCH /api/v1/app_installations/{id}` - **MCP tool:** `app_installations_update` - **Operation ID:** `app_installations.update` - **Scope:** Organization - **Permission:** `agents:admin` - **Risk tier:** `security` - **Dry run:** Supported (send `Ownrecord-Dry-Run: true`) - **Idempotency:** `Idempotency-Key` optional - **Modes:** Test and live - **Authentication:** API key with the `agents:admin` scope - **Since:** M10 ## Request ### Path parameters | Field | Type | Description | | ----- | ----------- | ----------- | | `id` | `ains_…` ID | | ### Body A JSON object (`Content-Type: application/json`): | Field | Type | Required | Description | | ----------------------------------- | -------------------------------------------------------------------------------------------------- | -------- | ----------- | | `scopes` | array of one of 84 values, e.g. `org:read`, `org:write`, `org:admin` (all in the OpenAPI document) | No | | | `limitTo` | object | No | | | `limitTo.entityIds` | array of `ent_…` ID | No | | | `limitTo.brandIds` | array of `brd_…` ID | No | | | `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 | | ## Response `200 OK` with a JSON object: | Field | Type | Description | | ----------------------------------- | -------------------------------------------------------------------------------------------------- | ----------- | | `id` | `ains_…` ID | | | `object` | `"app_installation"` | | | `orgId` | `org_…` ID | | | `app` | object | | | `app.id` | `ocl_…` ID | | | `app.name` | string | | | `app.publisher` | string | | | `app.logoUrl` | string or null | | | `app.verified` | boolean | | | `app.status` | one of `active`, `disabled` | | | `app.suspension` | object or null | | | `installedBy` | `usr_…` ID | | | `scopes` | array of one of 84 values, e.g. `org:read`, `org:write`, `org:admin` (all in the OpenAPI document) | | | `limitTo` | object | | | `limitTo.entityIds` | array of `ent_…` ID | | | `limitTo.brandIds` | array of `brd_…` ID | | | `limits` | object | | | `limits.rps` | integer or null | | | `limits.mutationsPerDay` | integer or null | | | `limits.amountLimits` | array of object | | | `limits.amountLimits[].operationId` | string | | | `limits.amountLimits[].perCall` | money or null | | | `limits.amountLimits[].perDay` | money or null | | | `status` | one of `active`, `paused`, `revoked` | | | `pausedReason` | one of `manual`, `installer_lost_access`, `platform_suspended`, `app_disabled` or null | | | `pausedAt` | string or null | | | `revokedAt` | string or null | | | `createdAt` | string | | | `updatedAt` | string | | ## Examples ### Read-only filings ```http PATCH /api/v1/app_installations/ains_01m4ttwd3veh9apbewxheq5xhc Authorization: Bearer or_test_… Content-Type: application/json { "scopes": [ "filings:read", "tasks:read" ] } ``` Response (`200`): ```json { "id": "ains_01m4ttwd3veh9apbewxheq5xhc", "object": "app_installation", "orgId": "org_01m4ttwd3veh9apbewxheq5xh3", "app": { "id": "ocl_01m4ttwd3veh9apbewxheq5xha", "name": "Ledgerly AI", "publisher": "Ledgerly AI B.V.", "logoUrl": null, "verified": true, "status": "active", "suspension": null }, "installedBy": "usr_01m4ttwd3veh9apbewxheq5xh6", "scopes": ["filings:read", "tasks:read"], "limitTo": { "entityIds": ["ent_01m4ttwd3veh9apbewxheq5xh4"], "brandIds": [] }, "limits": { "rps": null, "mutationsPerDay": null, "amountLimits": [] }, "status": "active", "pausedReason": null, "pausedAt": null, "revokedAt": null, "createdAt": "2026-10-25T09:00:00.000Z", "updatedAt": "2026-10-26T14:30:00.000Z" } ``` ### Ten changes a day, refunds up to €100 a day ```http PATCH /api/v1/app_installations/ains_01m4ttwd3veh9apbewxheq5xhc Authorization: Bearer or_test_… Content-Type: application/json { "limits": { "mutationsPerDay": 10, "amountLimits": [ { "operationId": "refunds.create", "perDay": { "amount": "100000000", "currency": "EUR" } } ] } } ``` Response (`200`): ```json { "id": "ains_01m4ttwd3veh9apbewxheq5xhc", "object": "app_installation", "orgId": "org_01m4ttwd3veh9apbewxheq5xh3", "app": { "id": "ocl_01m4ttwd3veh9apbewxheq5xha", "name": "Ledgerly AI", "publisher": "Ledgerly AI B.V.", "logoUrl": null, "verified": true, "status": "active", "suspension": null }, "installedBy": "usr_01m4ttwd3veh9apbewxheq5xh6", "scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"], "limitTo": { "entityIds": ["ent_01m4ttwd3veh9apbewxheq5xh4"], "brandIds": [] }, "limits": { "rps": null, "mutationsPerDay": 10, "amountLimits": [ { "operationId": "refunds.create", "perCall": null, "perDay": { "amount": "100000000", "currency": "EUR" } } ] }, "status": "active", "pausedReason": null, "pausedAt": null, "revokedAt": null, "createdAt": "2026-10-25T09:00:00.000Z", "updatedAt": "2026-10-26T14:30:00.000Z" } ``` ## Errors | Code | HTTP status | When | What to do | | ---------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A scope isn't one the installation already has, or a limit can't work (e.g. an amount limit on an operation that moves no amount). | Fix the fields listed in `details.issues` and send the request again. | | [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404 | No such installation, or an entity or brand in limitTo doesn't exist. | 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 installation 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): [`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_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).