Topolo Docs Topolo Platform
Open workspace

Disable a connected app

Disable an organization app connection and delete the Notify subscriptions it owns, or withdraw your own pending request, through Topolo Developers.

Disable an organization app connection and delete the Notify subscriptions it owns, or withdraw your own pending request, through Topolo Developers.

Action app_topolo_one.connections.disable · POST /api/connections/{consumerAppId}/{providerAppId}/disable. Intended audience: public.

Catalog flags: readOnly=False, requiresConfirmation=True, destructive=True, agentAccess=confirm. HTTP method and empty permission fields do not override the actual effects or authority below.

Authority and prerequisites

  • Declared authorization mode=runtime, requiredPermission=empty; actual source identity/resource checks below remain mandatory.
  • Discover the actual identifier and current intended state within existing authority. Examples grant no access and are not executable probes.

Identifiers

  • Use the active organization and canonical app pair from authorized current connection discovery. No organization/recipient/target override is accepted.

Input

  • consumerAppId: type="string"; pattern="^app_[a-z0-9]+(?:_[a-z0-9]+)+$". Required.
  • providerAppId: type="string"; pattern="^app_[a-z0-9]+(?:_[a-z0-9]+)+$". Required.

The exact native input/output schemas are retained in the hidden paired layer for this version. Top-level undeclared fields are rejected. Nested open records and semantic prerequisites still need source checks.

Effects and important boundaries

  • Calls the Developers connections.disable action for the pair in the active organization as the signed-in user.
  • Deletes every Notify subscription the connection owns, then removes the connection and keeps it as history. A member may only withdraw their own pending request.
  • One owns no connection state. It authenticates the signed-in user and active organization, then calls the published Developers actions as that user. Empty One permission metadata does not make the operation anonymous.
  • Developers enforces connections:read/write, active organization, provider entitlement and organization-admin versus requesting-member rules. One does not grant those permissions or substitute another organization.
  • Use canonical consumer/provider app IDs from the declared catalog. Action scopes/events and declared connection state are not themselves grants to execute the provider app.
  • Error or stateError leaves state unknown. Do not normalize an inaccessible/missing action or a failed subscription cleanup into an inactive/successful connection.
  • Deletes connection-owned Notify subscriptions before removing the connection while keeping history. A member can only withdraw their own pending request. Re-enabling creates fresh subscriptions and is not an exact undo.

Refusals, failures and recovery

  • 401 auth_error: Authenticate using the required credential type for this action; service-only actions require the registered Auth service identity.
  • 403 organization_required: Switch the credential’s active context to the organization whose connections you manage; connections always act for the active organization.
  • 403 permission_denied: Developers refused the caller: the user needs the app_topolo_developers.connections:write permission in the active organization. Ask an organization admin; One cannot grant it.
  • 403 organization_admin_required: Ask an organization admin; members can only withdraw their own pending request.
  • 404 connection_not_found: There is no live connection for this pair; read connections.overview.
  • 502 subscription_cleanup_failed: Read connections.status for the failing subscriptions, then disable again.
  • 404 unknown_action: The Developers connection action is not published in this environment yet. Nothing was read or changed; retry after Developers publishes it.
  • 422 invalid_input: Use canonical application ids (app_<owner>_<name>) from connections.overview; an enable or disable body may only repeat the path pair.

Enable the same pair again; an admin enable provisions fresh subscriptions. If subscription cleanup failed the connection stays degraded; disable again to retry.

Verification

  • Read connections.status for the pair and confirm state needs_setup or not_connected with no live connection.
  • Retain actual request/receipt identifiers securely, preserve UNKNOWN effects and reconcile before any retry.

Run a reviewed request

Discover the current action and its resource requirements before running it. Save the approved input as reviewed-input.json; replace synthetic examples with values obtained through the intended authorized workflow. If discovery requires a resource binding, provide its published type and resolved ID separately on both plan and call. Stop if validation fails or the plan is not executable.

topolo actions get app_topolo_one.connections.disable --json
topolo actions validate app_topolo_one.connections.disable --data @reviewed-input.json --json
topolo actions plan app_topolo_one.connections.disable --data @reviewed-input.json --confirm --json
topolo actions call app_topolo_one.connections.disable --data @reviewed-input.json --confirm --json

--confirm must represent approval of the actual request and its effects. The examples do not supply that approval.

Worked examples

All examples are synthetic and unrun. They cannot authorize access, create human consent, prove media/provider success or establish financial/customer state. Placeholder tokens are unusable. No contact, payment, notification, provisioning or business read was executed.

Authorized connection result illustration

SOURCE-AUTHORED SYNTHETIC, UNRUN. Output assessment: PASS_STRUCTURAL_ONLY_UNRUN.

Input:

{
  "consumerAppId": "app_topolo_socialize",
  "providerAppId": "app_topolo_brand"
}

Output illustration or error excerpt:

{
  "success": true,
  "data": {
    "outcome": "disabled",
    "connection": null
  }
}

200 hypothetical source envelope only; nested connection fields are illustrative open records and are not verified live state.

Refusal or failure

SOURCE-AUTHORED SYNTHETIC, UNRUN. Source-derived error-code excerpt only; messages/envelope can differ by layer or locale. Not a captured response. Output assessment: ERROR_EXCERPT_NOT_SUCCESS_SCHEMA.

Input:

{
  "consumerAppId": "app_topolo_socialize",
  "providerAppId": "app_topolo_brand"
}

Output illustration or error excerpt:

{
  "error": "organization_required"
}

No active organization means no connection read or mutation.

Invalid input: stop at schema validation

SOURCE-AUTHORED SYNTHETIC, UNRUN. null is a no-response sentinel, not returned JSON null. Output assessment: NOT_APPLICABLE_NO_REQUEST.

Input:

{
  "providerAppId": "app_topolo_brand"
}

Output illustration or error excerpt:

null

Intentionally invalid input; no request was issued and no HTTP response/status is asserted.

Boundary: subscription cleanup failed

SOURCE-AUTHORED SYNTHETIC, UNRUN. Output assessment: ERROR_EXCERPT_NOT_SUCCESS_SCHEMA.

Input:

{
  "consumerAppId": "app_topolo_socialize",
  "providerAppId": "app_topolo_brand"
}

Output illustration or error excerpt:

{
  "error": "subscription_cleanup_failed"
}

502 can leave the connection degraded with subscriptions requiring reconciliation. Do not claim removal or blindly replay.

Source and verification limits

Reviewed against cb18601dad6735f8140a4c81e9650d9fc3599f9a at apps/api/src/connection-routes.ts and the published action schema on 2026-10-20. Examples are synthetic and unrun. Source review and schema validation do not prove current deployed behavior, provider completion or business delivery. Response excerpts are labelled where incomplete.

Change log

  • 2026-10-20: Prepared the action guide with paired agent schemas, permission and effect boundaries, worked examples, verification and recovery instructions. Independently checked the pinned source; publication and runtime verification remain separate.