Topolo Docs Topolo Platform
Open workspace

Read connected app status

Read one consumer and provider connection in the active organization, with declared scopes, events, approval and Notify subscription health from Topolo Developers.

Read one consumer and provider connection in the active organization, with declared scopes, events, approval and Notify subscription health from Topolo Developers.

Action app_topolo_one.connections.status · GET /api/connections/{consumerAppId}/{providerAppId}. 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

  • 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

  • Reads one consumer and provider connection in the active organization from Developers: state, reasons, the current declaration with scopes and event versions, entitlements, approval and each Notify subscription’s health. It changes nothing.
  • 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.

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.
  • 422 invalid_input: Use canonical application ids (app_<owner>_<name>) from connections.overview; an enable or disable body may only repeat the path pair.

This action does not change service state.

Verification

  • Inspect data.state and data.reasons, data.declaration and data.connection (requestedBy, approvedBy, approvedAt, lastError and subscriptions).
  • 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.status --json
topolo actions validate app_topolo_one.connections.status --data @reviewed-input.json --json
topolo actions plan app_topolo_one.connections.status --data @reviewed-input.json --json
topolo actions call app_topolo_one.connections.status --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:

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

Output illustration or error excerpt:

{
  "success": true,
  "data": {
    "consumerAppId": "app_topolo_socialize",
    "providerAppId": "app_topolo_brand",
    "state": "needs_setup",
    "reasons": [],
    "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: dependency action not published

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": "unknown_action"
}

404 is a dependency capability gap, not evidence that this pair has no connection.

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.