Skip to content
Docs
APISign inStart free

Pause an installed app

The app_installations.pause operation: POST /api/v1/app_installations/{id}/pause in the REST API and the app_installations_pause tool in the MCP server.

POST/api/v1/app_installations/{id}/pause

Pauses an installed app: its access tokens and refresh tokens stop working in the organization at once, and it can't act there until resumed (app_installations.resume), after which it must ask for authorization again. Pausing a paused app changes nothing (one paused because its installer left stays so, keeping its tokens for after the re-assignment).

At a glance

  • REST: POST /api/v1/app_installations/{id}/pause
  • MCP tool: app_installations_pause
  • Operation ID: app_installations.pause
  • 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

FieldTypeDescription
idains_… ID

Body

This operation takes no body.

Response

200 OK with a JSON object:

FieldTypeDescription
idains_… ID
object"app_installation"
orgIdorg_… ID
appobject
app.idocl_… ID
app.namestring
app.publisherstring
app.logoUrlstring or null
app.verifiedboolean
app.statusone of active, disabled
app.suspensionobject or null
installedByusr_… ID
scopesarray of one of 84 values, e.g. org:read, org:write, org:admin (all in the OpenAPI document)
limitToobject
limitTo.entityIdsarray of ent_… ID
limitTo.brandIdsarray of brd_… ID
limitsobject
limits.rpsinteger or null
limits.mutationsPerDayinteger or null
limits.amountLimitsarray of object
limits.amountLimits[].operationIdstring
limits.amountLimits[].perCallmoney or null
limits.amountLimits[].perDaymoney or null
statusone of active, paused, revoked
pausedReasonone of manual, installer_lost_access, platform_suspended, app_disabled or null
pausedAtstring or null
revokedAtstring or null
createdAtstring
updatedAtstring

Examples

Pause an app

HTTP
POST /api/v1/app_installations/ains_01m4ttwd3veh9apbewxheq5xhc/pause
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14

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": null,
    "amountLimits": []
  },
  "status": "paused",
  "pausedReason": "manual",
  "pausedAt": "2026-10-26T14:30:00.000Z",
  "revokedAt": null,
  "createdAt": "2026-10-25T09:00:00.000Z",
  "updatedAt": "2026-10-26T14:30:00.000Z"
}

Errors

CodeHTTP statusWhenWhat to do
validation_failed400The installation is revoked.Fix the fields listed in details.issues and send the request again.
resource_not_found404No installation with this ID exists in the organization.Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
version_conflict409The installation changed at the same moment; retry.Fetch the object again and retry the change.
permission_denied403You 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_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.