Action: app_topolo_developers.connections.list.
Outcome
Read bounded stored connections, approval and subscription metadata in the active organization.
GET /api/developer-console/connections
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.
Optional consumerAppId,providerAppId use canonical app ids; status is needs_approval,active,paused,degraded or revoked. All filters combine. There is no app slug,organizationId,cursor,limit or includeRemoved option on this action.
Result data is {organizationId,connections,count}. count is connections.length, at most500, not an unbounded organization total. Query filters active organization and removed_at IS NULL, then optional app/status predicates, sorts consumer_app_id/provider_app_id and uses hard LIMIT500. No next cursor or hasMore exists; do not claim completeness when count reaches500.
Each complete record contains id,organizationId,consumerAppId,providerAppId,status,workspaceScope,declaration,declarationDigest,declarationSource,lastError,requestedBy,requestedAt,approvedBy,approvedAt,removedBy,removedAt,createdAt,updatedAt,subscriptions,referenceSubscriptions. workspaceScope is all or linked; it is application connection policy, not a selected workspace id.
declaration is parsed stored JSON of any shape, including null; invalid declaration_json becomes null rather than omitting the connection. declarationDigest,lastError,approvedBy,approvedAt,removedBy,removedAt are nullable. Live rows have removedAt:null because of this query; removedBy remains a nullable mapped stored value. Declaration data is a saved snapshot, not the current published capability contract or an authority grant.
subscriptions entries contain sourceAppId,eventType,eventVersion,subscriptionId|null,status (provisioned|failed),lastError|null,updatedAt. referenceSubscriptions add purpose (changed|removed) and referenceTypes:string[]. Both collections are always included and may be empty. They are filtered by exact connection id and ordered by source_app_id,event_type. eventVersion uses Number conversion; data quality/storage constraints are not revalidated by this mapper.
referenceTypes is parsed with JSON.parse without the declaration fallback. A malformed stored reference_types_json can fail the list rather than produce a partial successful row; no silent invented [] is a documented recovery. The base row read and the two subscription reads are sequential and are not a transactional snapshot.
Stored status,approval timestamps,subscription id and provisioned state are not a fresh permission, provider health or event delivery receipt. Removed history is excluded rather than deleted by this read. Retain current resource/identity context and minimize data forwarded outside the organization.
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
One stored degraded connection with both subscription collections
COMPLETE SYNTHETIC UNRUN HTTP200. Every mapped ConnectionRecord field is included; approval and subscription records are historical stored facts, not current delivery or access proof. All identifiers are fictional.
Request:
{
"status": "degraded"
}
Complete response body:
{
"success": true,
"message": "OK",
"data": {
"organizationId": "org_docs_fixture",
"connections": [
{
"id": "conn_docs_fixture",
"organizationId": "org_docs_fixture",
"consumerAppId": "app_example_consumer",
"providerAppId": "app_example_provider",
"status": "degraded",
"workspaceScope": "linked",
"declaration": {
"actions": [
{
"action": "app_example_provider.items.list",
"scopes": [
"items:read"
],
"resource": "workspace",
"optional": false,
"purpose": "Read example items"
}
],
"events": []
},
"declarationDigest": null,
"declarationSource": "topolo.app.json",
"lastError": "Synthetic subscription provisioning failure",
"requestedBy": "user_docs_requester",
"requestedAt": "2026-10-21T08:00:00.000Z",
"approvedBy": "user_docs_approver",
"approvedAt": "2026-10-21T08:00:00.000Z",
"removedBy": null,
"removedAt": null,
"createdAt": "2026-10-21T08:00:00.000Z",
"updatedAt": "2026-10-21T08:00:00.000Z",
"subscriptions": [
{
"sourceAppId": "app_example_provider",
"eventType": "example.updated",
"eventVersion": 1,
"subscriptionId": null,
"status": "failed",
"lastError": "Synthetic provisioning failure",
"updatedAt": "2026-10-21T08:00:00.000Z"
}
],
"referenceSubscriptions": [
{
"sourceAppId": "app_example_provider",
"eventType": "example.reference.changed",
"eventVersion": 1,
"purpose": "changed",
"referenceTypes": [
"example.item"
],
"subscriptionId": "whs_docs_fixture",
"status": "provisioned",
"lastError": null,
"updatedAt": "2026-10-21T08:00:00.000Z"
}
]
}
],
"count": 1
}
}
count is returned row count. A failed subscription can have null subscriptionId and a provisioning error; provisioned does not prove an event was delivered.
Successful empty filtered collection
COMPLETE SYNTHETIC UNRUN HTTP200 after authentication and organization checks succeed and no live rows match. Removed rows are excluded; this does not mean a provider or catalog was unavailable.
Request:
{
"consumerAppId": "app_example_consumer",
"providerAppId": "app_example_provider",
"status": "needs_approval"
}
Complete response body:
{
"success": true,
"message": "OK",
"data": {
"organizationId": "org_docs_fixture",
"connections": [],
"count": 0
}
}
Do not create, approve or enable a connection to make the collection nonempty.
Authenticated caller has no active organization
COMPLETE SYNTHETIC UNRUN HTTP403 from actorFor before selected store lookup.
Request:
{}
Complete response body:
{
"success": false,
"error": {
"message": "An active organization is required to manage app connections",
"code": "organization_required"
}
}
Restore the intended active organization through supported context controls; never pass organizationId as a guessed filter or broaden permission after a refusal.
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 records, full stored rows/subscriptions, combined filters and the500-row/no-cursor limit. Complete worked success responses are source-derived synthetic UNRUN; no app/provider/authorization/runtime operation or source-to-serving qualification is claimed.