Topolo Docs Topolo Platform
Open workspace

List organization connected apps

List every declared app-to-app connection with the active organization’s live connection state, read from Topolo Developers as the signed-in user.

List every declared app-to-app connection with the active organization’s live connection state, read from Topolo Developers as the signed-in user.

Action app_topolo_one.connections.overview · GET /api/connections. Intended audience: public.

Catalog flags: readOnly=True, requiresConfirmation=False, destructive=False, agentAccess=auto. 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

Pass {}; no body/query recipient override is accepted.

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

  • Reads the published Developers connection catalog and the active organization’s live connections as the signed-in user, without changing state.
  • Each declared consumer and provider pair is returned once. A pair without a live connection carries the state Developers derives for it (needs_setup or not_connected); a pair whose state could not be read carries stateError instead of a guessed state.
  • 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.
  • Returns each declared consumer/provider pair once, with declared actions/scopes and event versions. Live rows whose declaration disappeared remain visible with connection_not_declared.

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:read permission in the active organization. Ask an organization admin; One cannot grant it.
  • 404 unknown_action: The Developers connection action is not published in this environment yet. Nothing was read or changed; retry after Developers publishes it.

This action does not change service state; read it again after the cause of a refusal or stateError is resolved.

Verification

  • Inspect data.pairs: each pair names its consumer, provider, declared actions with scopes and events with versions, the live connection (or null) and its state. Read connections.status for any pair before changing it.
  • 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.overview --json
topolo actions validate app_topolo_one.connections.overview --data @reviewed-input.json --json
topolo actions plan app_topolo_one.connections.overview --data @reviewed-input.json --json
topolo actions call app_topolo_one.connections.overview --data @reviewed-input.json --json

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:

{}

Output illustration or error excerpt:

{
  "success": true,
  "data": {
    "organizationId": "org_example",
    "pairs": []
  }
}

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:

{}

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:

{
  "unexpectedRecipientId": "other_user"
}

Output illustration or error excerpt:

null

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

Boundary: one pair state could not be read

SOURCE-AUTHORED SYNTHETIC, UNRUN. Partial excerpt; not a complete response. Output assessment: PARTIAL_EXCERPT_NOT_COMPLETE_SCHEMA.

Input:

{}

Output illustration or error excerpt:

{
  "success": true,
  "data": {
    "pairs": [
      {
        "state": null,
        "stateError": {
          "code": "permission_denied",
          "message": "State unavailable"
        }
      }
    ]
  }
}

Partial excerpt: preserve the pair’s stateError and unknown state. An empty or inaccessible state is not needs_setup.

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.