List workspaces

List active canonical workspaces the caller may use in one application and organization. Automatically provisioned first workspaces use the organization display name unless explicitly named; existing workspace names are preserved.

Outcome

Before you start

Verify the credential with topolo whoami --json and inspect the exact published action. Stop on runtime authorization denial; do not widen permissions or switch contexts automatically.
Discover the target application and use the organization carried by the credential. A request organizationId is not a context override.
Use workspaces.list for the same target application and organization. Inspect policy.canCreate and reason; ownership, application access and permission to create additional workspaces are distinct.
First-use provisioning may create the organization-owned default when no active workspace exists. This GET is not a guarantee of zero storage effects. Inspect the published effects before discovery in a new application.

Discover the target

topolo actions get app_topolo_auth.workspaces.list --detail --json
topolo apps --json
topolo whoami --json
topolo workspaces list topolo-docs --json

Input fields

Field	Required	Meaning
`org_id`	Yes	Active organization identifier from credential identity. Workspace list uses org_id; mutations use organizationId.
`app_id`	Yes	Exact target application identifier from discovery. This list is limited to one application and organization.

Effects

Lists canonical workspaces and caller-specific creation permission and policy for one application and organization.
When no active workspace exists, first-use provisioning atomically provisions the organization-owned default workspace and records an audit event. This GET is not guaranteed to have zero storage effects.

Interpret the response

data.workspaces contains the accessible canonical identities. data.policy.canCreate/reason is the advisory caller-specific decision for additional creation, and the create call evaluates it again. accessMode and canManageAll describe this caller; creation permission, organization limits and per-user limits are separate constraints.

Worked examples

These are raw target-handler responses, not gateway or CLI envelopes. They were captured in a local test with simulated dependencies. Fixture identifiers and credentials are illustrative and cannot authorize a live call. Discover your own organization, application, workspace and key ids. Local CLI/stdio MCP may replace credential strings with protected references; preserve the reference and do not extract the underlying secret.

Minimal example

Input · payload.json:


{
  "org_id": "org_fixture",
  "app_id": "app_topolo_docs"
}

CLI:


topolo actions validate app_topolo_auth.workspaces.list --data @payload.json --json
topolo actions plan app_topolo_auth.workspaces.list --data @payload.json --json
topolo actions call app_topolo_auth.workspaces.list --data @payload.json --json

MCP:


{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.workspaces.list",
    "input": {
      "org_id": "org_fixture",
      "app_id": "app_topolo_docs"
    }
  }
}

Captured local handler response · HTTP 200:


{
  "success": true,
  "message": "Workspaces fetched",
  "data": {
    "appId": "app_topolo_docs",
    "organizationId": "org_fixture",
    "accessMode": "restricted",
    "canManageAll": false,
    "workspaces": [
      {
        "id": "ws_first_fixture",
        "appId": "app_topolo_docs",
        "organizationId": "org_fixture",
        "name": "First reference",
        "avatar": {
          "kind": "preset",
          "presetId": "orbit"
        },
        "slug": "ws_first_fixture",
        "status": "active",
        "isDefault": true,
        "ownerUserId": "usr_fixture",
        "createdByUserId": "usr_fixture",
        "createdAt": 1,
        "updatedAt": 1,
        "archivedAt": null
      }
    ],
    "policy": {
      "mode": "multi",
      "limit": null,
      "remaining": null,
      "userLimit": null,
      "userRemaining": null,
      "canCreate": true,
      "reason": "ok"
    }
  },
  "timestamp": "2026-10-02T14:48:16.375Z"
}

Workflow example

Input · payload.json:


{
  "org_id": "org_fixture",
  "app_id": "app_topolo_docs"
}

CLI:


topolo actions validate app_topolo_auth.workspaces.list --data @payload.json --json
topolo actions plan app_topolo_auth.workspaces.list --data @payload.json --json
topolo actions call app_topolo_auth.workspaces.list --data @payload.json --json

MCP:


{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.workspaces.list",
    "input": {
      "org_id": "org_fixture",
      "app_id": "app_topolo_docs"
    }
  }
}

Captured local handler response · HTTP 200:


{
  "success": true,
  "message": "Workspaces fetched",
  "data": {
    "appId": "app_topolo_docs",
    "organizationId": "org_fixture",
    "accessMode": "restricted",
    "canManageAll": false,
    "workspaces": [
      {
        "id": "ws_existing_fixture",
        "appId": "app_topolo_docs",
        "organizationId": "org_fixture",
        "name": "Existing reference",
        "avatar": {
          "kind": "preset",
          "presetId": "orbit"
        },
        "slug": "ws_existing_fixture",
        "status": "active",
        "isDefault": true,
        "ownerUserId": "usr_fixture",
        "createdByUserId": "usr_fixture",
        "createdAt": 1,
        "updatedAt": 1,
        "archivedAt": null
      }
    ],
    "policy": {
      "mode": "multi",
      "limit": null,
      "remaining": null,
      "userLimit": null,
      "userRemaining": null,
      "canCreate": true,
      "reason": "ok"
    }
  },
  "timestamp": "2026-10-02T14:48:16.399Z"
}

Verify the result

Require the returned appId and organizationId to match the request. Use returned workspace ids; preserve the default selection. The result may be the freshly provisioned first workspace. Confirm repeated discovery preserves its id.

Errors and recovery

Listing may provision the first default workspace. Do not delete it as an automatic inverse of discovery; archive only through a published owning-application operation after emptiness and intended removal are established.

Evidence boundary

The handler test proves response shape and control flow under the listed simulated dependencies. It does not prove real grant evaluation, durable SQL storage, protected credential-store handoff, target application synchronization or downstream use of a key.