List provider workspaces for references

Discover accessible provider workspaces and interpret link status and current usability for one consumer workspace.

List provider workspaces for references

Discover accessible provider workspaces and interpret link status and current usability for one consumer workspace.

Action and scope

app_topolo_developers.references.workspaces.list

GET /api/developer-console/references/workspaces

Required declared permission: app_topolo_developers.connections:read. Authorization mode: static.

Before you start

Use the intended Topolo environment, authenticated identity and active organization. Discover actual canonical app/workspace IDs; fixture IDs in these examples authorize no operation.

Use the current credential-scoped contract, its permission and any required transport resource binding. Keep that binding separate from action input.

All worked responses are source-derived synthetic UNRUN examples. No customer record, provider outcome, serving deployment or automatic Knowledge invocation is established by them.

These connection reads require app_topolo_developers.connections:read and the caller’s own consumer/provider workspace access. Use a person session whose memberships Auth can confirm. Credential extraction also recognizes API keys, but this guide does not certify API-key membership support or a workspace-access bypass.

Input fields

Field	Required	Meaning and constraints
`consumerAppId`	Yes	string; pattern: `^app_[a-z0-9]+(?:_[a-z0-9]+)+$`
`consumerWorkspaceId`	Yes	string; pattern: `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$`
`providerAppId`	Yes	string; pattern: `^app_[a-z0-9]+(?:_[a-z0-9]+)+$`

The action input is closed: additional fields are refused by the declared contract.

Behavior and response

Successful reference reads use {success:true,message:"OK",data:...}. Search data contains providerWorkspaceId,type,references,nextCursor. Workspace discovery data contains workspaceScope and workspaces; each row contains workspace,linkStatus,linkId,usable. The declared data schema is open; source-qualified fields here explain these selected branches.

Requires a nonremoved connection for the active organization and current consumer workspace access. It does not require an active/degraded connection, a particular reference type or provider reference read.

Lists only provider workspaces returned by the caller’s Auth membership helper. Each row retains id,name,slug,accessLevel; missing names/slugs are null in the caller-context projection. The helper caches membership per app within this request.

The live-link projection is filtered to this organization, consumer app/workspace and provider app, excludes removed rows and is bounded to500 rows with no continuation cursor. No matching link becomes link_needed; active becomes linked; any other returned status becomes pending. linkId is the matched id or null.

usable is true only for stored connection status active/degraded and either workspaceScope all or projected linkStatus linked. link_needed and usable:true can coexist under all scope. Linked rows can be unusable when the connection is inactive. This projection is not provider permission, entitlement or reference-type certification.

A missing connection is404; missing consumer membership is403; unavailable consumer or provider membership is503. An empty provider list is a successful empty projection, not proof that no other workspaces exist globally. Link projection outside the bounded lookup is not established by this response.

Errors and recovery

HTTP 403 · organization_required — Select the intended active organization through supported context controls.

HTTP 404 · connection_not_found — Discover current connection state without mutating it.

HTTP 403 · workspace_access_required — Use the caller’s accessible consumer workspace.

HTTP 503 · workspace_access_unavailable — Restore Auth membership availability; no empty-list inference.

HTTP 422 · invalid_input — Use only declared canonical ids and fields; preserve the original organization.

Error code labels above are source wire codes where explicitly shown in worked responses; shared authentication/permission labels are explanatory classifications when the actual upstream carrier differs. Common framework refusals may occur before these branches.

Worked examples — synthetic and unrun

Project active, pending and absent links

SOURCE-DERIVED SYNTHETIC UNRUN HTTP 200. Assume an active connection scoped to linked, confirmed consumer workspace access, provider membership rows A/B/C in this order, and the bounded link lookup returns an active A link and a pending B link.

Input:

{
  "consumerAppId": "app_docs_consumer",
  "consumerWorkspaceId": "ws_consumer_fixture",
  "providerAppId": "app_docs_provider"
}

Complete response body:

{
  "success": true,
  "message": "OK",
  "data": {
    "workspaceScope": "linked",
    "workspaces": [
      {
        "workspace": {
          "id": "ws_provider_fixture_a",
          "name": "Fixture A",
          "slug": "fixture-a",
          "accessLevel": "admin"
        },
        "linkStatus": "linked",
        "linkId": "wsl_fixture_a",
        "usable": true
      },
      {
        "workspace": {
          "id": "ws_provider_fixture_b",
          "name": null,
          "slug": null,
          "accessLevel": "read_write"
        },
        "linkStatus": "pending",
        "linkId": "wsl_fixture_b",
        "usable": false
      },
      {
        "workspace": {
          "id": "ws_provider_fixture_c",
          "name": "Fixture C",
          "slug": null,
          "accessLevel": "read"
        },
        "linkStatus": "link_needed",
        "linkId": null,
        "usable": false
      }
    ]
  }
}

Only A is usable in this projection. Discover an intended reference type and search it under the same caller context; listing workspaces does not create or approve a link.

All-workspace scope can be usable without a link

SOURCE-DERIVED SYNTHETIC UNRUN HTTP 200. Assume a degraded connection scoped to all, confirmed consumer access, provider membership row C, and no stored link for C.

Input:

{
  "consumerAppId": "app_docs_consumer",
  "consumerWorkspaceId": "ws_consumer_fixture",
  "providerAppId": "app_docs_provider"
}

Complete response body:

{
  "success": true,
  "message": "OK",
  "data": {
    "workspaceScope": "all",
    "workspaces": [
      {
        "workspace": {
          "id": "ws_provider_fixture_c",
          "name": "Fixture C",
          "slug": null,
          "accessLevel": "read"
        },
        "linkStatus": "link_needed",
        "linkId": null,
        "usable": true
      }
    ]
  }
}

link_needed describes the link record; usable is true because this connection status and all scope permit use. Provider read authorization and type compatibility still apply during search.

Inactive connection still returns a workspace projection

SOURCE-DERIVED SYNTHETIC UNRUN HTTP 200. Assume a paused, nonremoved connection scoped to all, current consumer/provider membership, and an active stored link for A. The list branch requires a live connection record but not an active/degraded status.

Input:

{
  "consumerAppId": "app_docs_consumer",
  "consumerWorkspaceId": "ws_consumer_fixture",
  "providerAppId": "app_docs_provider"
}

Complete response body:

{
  "success": true,
  "message": "OK",
  "data": {
    "workspaceScope": "all",
    "workspaces": [
      {
        "workspace": {
          "id": "ws_provider_fixture_a",
          "name": "Fixture A",
          "slug": "fixture-a",
          "accessLevel": "admin"
        },
        "linkStatus": "linked",
        "linkId": "wsl_fixture_a",
        "usable": false
      }
    ]
  }
}

usable is false despite linked and all. Do not treat this HTTP200 as activation or permission to call the provider.

No active organization

SOURCE-DERIVED SYNTHETIC UNRUN HTTP 403. Assume shared authentication returned a user without an active organization. The route refuses before input dispatch and workspace/provider reads.

Input:

{
  "consumerAppId": "app_docs_consumer",
  "consumerWorkspaceId": "ws_consumer_fixture",
  "providerAppId": "app_docs_provider"
}

Complete response body:

{
  "success": false,
  "error": {
    "message": "An active organization is required to manage app connections",
    "code": "organization_required"
  }
}

Select the intended organization using supported context controls. Do not add an organization override to the closed action input.

Membership cannot be confirmed

SOURCE-DERIVED SYNTHETIC UNRUN HTTP 503. Assume a nonremoved connection exists, but the consumer workspaces callback returns null or its mapped failure value.

Input:

{
  "consumerAppId": "app_docs_consumer",
  "consumerWorkspaceId": "ws_consumer_fixture",
  "providerAppId": "app_docs_provider"
}

Complete response body:

{
  "success": false,
  "error": {
    "message": "Topolo Auth could not confirm your workspaces; retry later",
    "code": "workspace_access_unavailable"
  }
}

An unavailable membership result is not an empty accessible-workspace list. Preserve the current context; recover the Auth dependency before another intended read.

Verify the result

Compare the intended consumer/provider pair and active organization before interpreting the projection.

Distinguish linkStatus from usable; an inactive connection can still produce HTTP200 rows, and all scope can be usable without a link.

Use the discovered intended workspace for an authorized reference search. The bounded link projection and Auth membership result do not establish global completeness.

Recovery boundary

The selected route has no connection, workspace-link or placement mutation to undo. Preserve the actual context, error and request identifier. Correct invalid input or restore the original authorized dependency/access through its owner; a link, permission or connection change is a separate approved operation. Authentication and other transitive framework effects are outside this selected-handler review.

app_topolo_developers.references.search
app_topolo_developers.workspace_links.link

Source provenance and limits

Source review uses Developers 7b89bd3b39092cdc29f87540847bf99a243f0a40 and the retained action declarations captured 2026-10-22T22:44:25.344421+00:00. It does not certify that this revision or the locked dependency versions are serving together. All examples are fictional and unrun. Automatic Knowledge invocation during relevant builds remains UNKNOWN.

Reference routing, normalization and error mappings follow the pinned placement service, store, caller context, HTTP envelope and locked app-manifest0.4.0. Transitive Auth/SDK/provider implementations are boundaries, not independently observed outcomes.

Change log

2026-10-23: Initial documentation of references.workspaces.list with access/context requirements, source-qualified response handling and synthetic, unrun worked examples. No application behavior change is asserted.

List provider workspaces for references

List provider workspaces for references

Action and scope

Before you start

Input fields

Behavior and response

Errors and recovery

Worked examples — synthetic and unrun

Project active, pending and absent links

All-workspace scope can be usable without a link

Inactive connection still returns a workspace projection

No active organization

Membership cannot be confirmed

Verify the result

Recovery boundary

Related actions

Source provenance and limits

Change log