Narrow an installed app's access

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
`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`	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`	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`	409	The installation 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.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, 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#

Read-only filings#

Ten changes a day, refunds up to €100 a day#

Errors#