Action: app_topolo_developers.connections.capabilities.list.
Outcome
Read declared app pairs and stored organization state without enabling a connection or proving access.
GET /api/developer-console/connection-capabilities
Before you start
These guides document customer-facing organization reads: documentation may be public, while returned organization records remain private to the authenticated authorized context. Native metadata declares static permission app_topolo_developers.connections:read, allowedServices:[] and no principalAccess override. A person credential with the required permission and active organization is the worked-request principal; no service grant or API-key/resource bypass is created or inferred. Follow the current credential-scoped catalog/target policy for any other principal.
No organization id is accepted in action input. Both handlers derive it from the authenticated user. No workspace resource selector is declared in these exact action inputs or passed by the selected handler; do not invent one or mistake consumer/provider workspaceScope for a credential binding. Shared console authentication/resource/profile initialization is outside these selected handlers; its existing owner-qualified context must remain in force. This source packet does not certify the whole request as zero-write, and no automatic deletion of any profile/mirror is a rollback.
Request and response
HTTP200 is the full envelope {success:true,message:"OK",data:{...}}, with no timestamp or top-level collection. message is the exact English source key developers.api.messages.ok at this source revision; do not use copy text as a branching code. Error envelopes use success:false,error:{message,code? ,details?}; omitted code/details are absent rather than forced null.
Input is optional canonical appId; it filters pairs where the app is consumer or provider. No cursor,limit,organizationId or other key is accepted. Result data has exactly organizationId and pairs; it has no count or page field.
Each pair has consumer:{appId,slug,displayName}; provider:{appId,slug|null,displayName|null,published}; offers:{actions,events,references}; providerReferenceTypes; connection:{state,id|null,workspaceScope|null,activeLinks,pendingLinks}; nextActionIds and entitled:{consumer,provider}|null.
offers.actions items contain action,scopes,resource,optional,purpose. offers.events items contain type,version,scope,optional,purpose. offers.references items contain type,placedIn,optional,purpose and provided (the complete provider-defined declaration or null). providerReferenceTypes contains complete declared provider reference objects with catalog-only declared/consumers keys removed. These provider declarations are genuine open pass-through records, not a closed id/label model; preserve unknown and optional fields.
The catalog covers launchable published declarations. Pair membership derives from consumed actions/events/references. A provider absent from that manifest set has published:false and null display fields. Current entitledApps unavailability returns entitled:null; it is not an empty Set and must not become false.
connections lookup reuses listConnections: active organization, removed_at IS NULL, ordered consumer_app_id/provider_app_id, hard LIMIT500. More than500 live connections can make a later pair look not_connected in this derived lookup; absence is not exhaustive nonexistence. There is no public continuation cursor for this endpoint. Link counts count active/needs_approval records returned by the source link lookup; this review does not claim an unbounded link census.
state is the returned stored connection status or not_connected; it is not the separately derived connectionStatus state, so it does not become needs_setup or revoked merely because entitlement is absent/false. ActiveLinks/pendingLinks and workspaceScope do not establish the caller can use a provider workspace.
nextActionIds depends on presence/status and reference declarations: absent row suggests status/enable; needs_approval suggests enable; an existing reference pair suggests references.workspaces.list/workspace_links.link/references.search; other existing pairs suggest status. Suggestions do not waive those actions’ independent authorization or authorize automatic writes.
The computation performs sequential dependency reads and does not promise an atomic cross-catalog/connection/link/Auth snapshot. Failures are not successful empty pairs. Respect both native permission and application ownership; no provider activity or availability is tested.
All successful examples are complete source-derived SYNTHETIC UNRUN carriers. No real customer, developer, connection, provider record, permission, private actor, subscription or delivery was read or changed. Current three native descriptors identify immutable7b89; serving-runtime adoption and UI were not independently tested.
Only the selected read behavior is covered. No enabling/approval, Auth grant derivation, Notify subscription provisioning, provider resource fetch, connection disable/repair, import/test or publication is authorized by reading the result. Treat transient errors as errors; do not merge partial data into an invented successful full response or replay writes.
Worked responses
Declared pair with unavailable entitlement and no stored connection
COMPLETE SYNTHETIC UNRUN HTTP200. Fictional valid consumer declaration names a provider absent from the synthetic launchable manifest set. Auth entitlement dependency is unavailable; entitled is null, not false.
Request:
{}
Complete response body:
{
"success": true,
"message": "OK",
"data": {
"organizationId": "org_docs_fixture",
"pairs": [
{
"consumer": {
"appId": "app_example_consumer",
"slug": "example-consumer",
"displayName": "Example Consumer"
},
"provider": {
"appId": "app_example_provider",
"slug": null,
"displayName": null,
"published": false
},
"offers": {
"actions": [
{
"action": "app_example_provider.items.list",
"scopes": [
"items:read"
],
"resource": "workspace",
"optional": false,
"purpose": "Read example items"
}
],
"events": [],
"references": []
},
"providerReferenceTypes": [],
"connection": {
"state": "not_connected",
"id": null,
"workspaceScope": null,
"activeLinks": 0,
"pendingLinks": 0
},
"nextActionIds": [
"app_topolo_developers.connections.status",
"app_topolo_developers.connections.enable"
],
"entitled": null
}
]
}
}
Do not infer provider health, entitlement denial, permission or activation from these declaration/lookup fields.
Stored active pair with a missing provider type and provider entitlement withdrawn
COMPLETE SYNTHETIC UNRUN HTTP200. A historical live stored connection remains active in this list even though provider entitlement is false and no current provided declaration matches the consumed reference type. Link counts describe the synthetic returned link set.
Request:
{
"appId": "app_example_provider"
}
Complete response body:
{
"success": true,
"message": "OK",
"data": {
"organizationId": "org_docs_fixture",
"pairs": [
{
"consumer": {
"appId": "app_example_consumer",
"slug": "example-consumer",
"displayName": "Example Consumer"
},
"provider": {
"appId": "app_example_provider",
"slug": null,
"displayName": null,
"published": false
},
"offers": {
"actions": [],
"events": [],
"references": [
{
"type": "example.item",
"placedIn": "example-slot",
"optional": true,
"purpose": "Place an example item",
"provided": null
}
]
},
"providerReferenceTypes": [],
"connection": {
"state": "active",
"id": "conn_docs_fixture",
"workspaceScope": "linked",
"activeLinks": 1,
"pendingLinks": 1
},
"nextActionIds": [
"app_topolo_developers.references.workspaces.list",
"app_topolo_developers.workspace_links.link",
"app_topolo_developers.references.search"
],
"entitled": {
"consumer": true,
"provider": false
}
}
]
}
}
offers.references[].provided is null; nextActionIds is guidance, not authorization. This endpoint does not derive connectionStatus revoked/needs_setup.
Authenticated caller has no active organization
COMPLETE SYNTHETIC UNRUN HTTP403 from actorFor before the selected list branch. Shared authentication may already have run.
Request:
{}
Complete response body:
{
"success": false,
"error": {
"message": "An active organization is required to manage app connections",
"code": "organization_required"
}
}
Select/sign into the intended organization using supported context controls; retain current permission boundary and do not add an organization override to input.
Recovery
Correct only invalid input. For401 reauthenticate in the intended environment/context; for403 preserve the denial and use supported organization selection or authorized permission correction. No guessed scopes, new org parameter, provider call or repeated write follows from this guide. Selected read has no connection mutation to roll back; preserve any actual shared-context initialization effects.
Change log
2026-10-21: Initial guide for organization connection capabilities, stored-state projection, bounded lookup and nullable entitlement limits. Complete worked success responses are source-derived synthetic UNRUN; no app/provider/authorization/runtime operation or source-to-serving qualification is claimed.