Topolo Docs Topolo Platform
Open workspace

Enable or request a connected app

Enable a declared app connection as an organization admin, or record a member request for admin approval, through Topolo Developers.

Enable a declared app connection as an organization admin, or record a member request for admin approval, through Topolo Developers.

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

Catalog flags: readOnly=False, requiresConfirmation=True, destructive=False, 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.enable action for the pair in the active organization as the signed-in user.
  • An organization admin approves a pending request or enables the pair directly; event connections provision one Notify subscription per declared event (outcome activated, or degraded with the failure recorded). A member records a request for admin approval (outcome requested).
  • 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.
  • A member can request approval; an organization admin approves/enables. Event connections can provision Notify subscriptions. Read active/needs_approval/degraded and per-subscription errors, rather than treating any 200 as activation.

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 not_entitled: Entitle the organization to both apps named in error.details.appIds, then enable again. Nothing was changed.
  • 409 provider_contract_missing: The provider no longer publishes something the consumer declares; a matching release is required before the pair can be enabled.
  • 409 connection_paused: The connection is paused; resume is not available in phase 1. Read connections.status.
  • 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.

Disable the same pair to delete the provisioned subscriptions and remove the connection; enabling a degraded connection again retries only what failed.

Verification

  • Read connections.status for the same pair and confirm state active, needs_approval for a member request, or degraded with connection.lastError and per-subscription lastError.
  • 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.enable --json
topolo actions validate app_topolo_one.connections.enable --data @reviewed-input.json --json
topolo actions plan app_topolo_one.connections.enable --data @reviewed-input.json --confirm --json
topolo actions call app_topolo_one.connections.enable --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_support",
  "providerAppId": "app_topolo_crm"
}

Output illustration or error excerpt:

{
  "success": true,
  "data": {
    "outcome": "requested",
    "connection": {
      "id": "connection_example",
      "status": "requested"
    }
  }
}

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_support",
  "providerAppId": "app_topolo_crm"
}

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_crm"
}

Output illustration or error excerpt:

null

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

Boundary: provisioning degraded

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

Input:

{
  "consumerAppId": "app_topolo_support",
  "providerAppId": "app_topolo_crm"
}

Output illustration or error excerpt:

{
  "success": true,
  "data": {
    "outcome": "degraded",
    "connection": {
      "lastError": "illustrative provider failure"
    }
  }
}

Partial connection-record excerpt: success of the request is not active subscriptions. Reconcile failures before any authorized retry.

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.