Skip to content
Docs
APISign inStart free

Uninstall an app

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

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

Uninstalls an app from the organization: its tokens stop working there at once and the installation is kept as revoked with its audit trail. The app can be installed again later through the consent screen. Uninstalling an uninstalled app changes nothing.

At a glance

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

Uninstall an app

HTTP
POST /api/v1/app_installations/ains_01m4ttwd3veh9apbewxheq5xhc/revoke
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": "revoked",
  "pausedReason": null,
  "pausedAt": null,
  "revokedAt": "2026-10-26T14:30:00.000Z",
  "createdAt": "2026-10-25T09:00:00.000Z",
  "updatedAt": "2026-10-26T14:30:00.000Z"
}

Errors

CodeHTTP statusWhenWhat to do
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: validation_failed, 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.