List accessible workspaces

Outcome

List active workspaces the caller may access in one application and organization.

These examples prove local handler behavior with real isolated SQL and explicitly simulated identity/permission dependencies.

Before you start

• Verify identity and the current credential-scoped action contract before preparing input. Workspace-access operations require a consistent active organization context and target workspace authority; metadata discovery does not prove execution permission.

• Discover the existing canonical workspace in the exact application/organization and intended recipient. These actions do not provision identities, organization memberships, application seats or entitlement.

Discover the target

topolo whoami --json
topolo apps --json
topolo actions get app_topolo_auth.workspace_access.list_mine --detail --json

Read app_topolo_auth.workspace_access.list_mine for this organization/app; copy data.resources[].id. For management read workspace_access.members.list. Recipient candidates require current active membership and app access.

Input fields

Effects

• Reads the caller-specific canonical workspace projection; no membership changes.

Interpret the response

Raw target responses use success/message/data/timestamp. Grant returns HTTP 201; the other successes return 200. CLI/MCP envelopes may wrap or project the target response. Epoch-number record times differ from the ISO envelope timestamp.

list_mine data.resources contains canonical workspace records whose identifier is id. accessMode all and canManageAll true require organization owner/super_admin or valid platform authority; ordinary organization admin remains restricted. Owner and explicit unexpired invited_member grants drive the restricted projection.

members.list returns one owner, explicit member grants and at most 500 directory candidates. This directory has no continuation and is not guaranteed exhaustive. A candidate may still fail active membership/app assignment validation. No returned user data should be exported beyond the authorized workflow.

Member data.id is the grant id after profile and grant objects are combined; data.userId is the recipient identity id. Owner data.id is its user id. Owner profile can contain only id/name/accessRole when it is absent from the directory, and member profile fields can be absent. Profile activeContext/orgId describe that user context and do not replace the workspace organization boundary.

Grant is a natural-key upsert. Repetition changes scope, clears old revocation, resets expiry/metadata through creation defaults and preserves its id/createdAt. It does not create organization membership, application assignment, a seat or ownership. Audit persistence is nonfatal; successful grant/revoke/transfer does not prove an audit entry.

Member revoke returns userId/resourceId and removes explicit access only. Repetition returns NOT_FOUND. Owner removal returns CONFLICT. Organization-wide authority and independent application permissions still require separate verification.

The workspace owner and ownership projection update in one atomic access-database batch. Removing the new owner redundant grant and retaining/removing the previous owner grants occur afterward in separate writes; the full transfer is not atomic. A 500 can leave a new owner and a redundant member grant while previous-owner retention is unfinished.

A blind retry after partial transfer is unsafe: the former owner may be denied and a transfer to the now-current owner returns CONFLICT. Read members/current ownership first. The public revoke action refuses the current owner even if a redundant owner grant remains; this family has no customer cleanup operation for that partial state. Preserve evidence and seek authorized operator repair rather than inventing an endpoint or bypassing ownership.

Worked examples

These are complete raw target-handler responses, not CLI/gateway envelopes or live authorization proof. Replace synthetic identifiers using authorized discovery. Save only the reviewed input as payload.json; inspect validation and plan before executing. --confirm assumes the intended operation is approved. Metadata read-back requires separate recipient-principal and owning-application access tests.

Workspace owner sees only its owned workspace

Input · payload.json:

{
  "org_id": "org_example",
  "app_id": "app_topolo_campaigns"
}

CLI:

topolo actions validate app_topolo_auth.workspace_access.list_mine --data @payload.json --json
topolo actions plan app_topolo_auth.workspace_access.list_mine --data @payload.json --json
topolo actions call app_topolo_auth.workspace_access.list_mine --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.workspace_access.list_mine",
    "input": {
      "org_id": "org_example",
      "app_id": "app_topolo_campaigns"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Workspace access fetched",
  "data": {
    "organizationId": "org_example",
    "appId": "app_topolo_campaigns",
    "accessMode": "restricted",
    "canManageAll": false,
    "resources": [
      {
        "id": "ws_fixture_one",
        "appId": "app_topolo_campaigns",
        "organizationId": "org_example",
        "name": "Campaigns",
        "avatar": {
          "kind": "preset",
          "presetId": "orbit"
        },
        "slug": "campaigns",
        "status": "active",
        "isDefault": false,
        "ownerUserId": "usr_owner",
        "createdByUserId": null,
        "createdAt": 1790965443,
        "updatedAt": 1790965443,
        "archivedAt": null,
        "accessRole": "owner",
        "accessLevel": "read_write"
      }
    ]
  },
  "timestamp": "2026-10-02T18:24:03.952Z"
}

Organization owner sees every active workspace

Input · payload.json:

{
  "org_id": "org_example",
  "app_id": "app_topolo_campaigns"
}

CLI:

topolo actions validate app_topolo_auth.workspace_access.list_mine --data @payload.json --json
topolo actions plan app_topolo_auth.workspace_access.list_mine --data @payload.json --json
topolo actions call app_topolo_auth.workspace_access.list_mine --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.workspace_access.list_mine",
    "input": {
      "org_id": "org_example",
      "app_id": "app_topolo_campaigns"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Workspace access fetched",
  "data": {
    "organizationId": "org_example",
    "appId": "app_topolo_campaigns",
    "accessMode": "all",
    "canManageAll": true,
    "resources": [
      {
        "id": "ws_fixture_one",
        "appId": "app_topolo_campaigns",
        "organizationId": "org_example",
        "name": "Campaigns",
        "avatar": {
          "kind": "preset",
          "presetId": "orbit"
        },
        "slug": "campaigns",
        "status": "active",
        "isDefault": false,
        "ownerUserId": "usr_owner",
        "createdByUserId": null,
        "createdAt": 1790965443,
        "updatedAt": 1790965443,
        "archivedAt": null,
        "accessRole": "organization_admin",
        "accessLevel": "admin"
      },
      {
        "id": "ws_fixture_two",
        "appId": "app_topolo_campaigns",
        "organizationId": "org_example",
        "name": "Research",
        "avatar": {
          "kind": "preset",
          "presetId": "orbit"
        },
        "slug": "research",
        "status": "active",
        "isDefault": false,
        "ownerUserId": "usr_other_owner",
        "createdByUserId": null,
        "createdAt": 1790965443,
        "updatedAt": 1790965443,
        "archivedAt": null,
        "accessRole": "organization_admin",
        "accessLevel": "admin"
      }
    ]
  },
  "timestamp": "2026-10-02T18:24:03.954Z"
}

Ordinary organization admin has restricted projection

Input · payload.json:

{
  "org_id": "org_example",
  "app_id": "app_topolo_campaigns"
}

CLI:

topolo actions validate app_topolo_auth.workspace_access.list_mine --data @payload.json --json
topolo actions plan app_topolo_auth.workspace_access.list_mine --data @payload.json --json
topolo actions call app_topolo_auth.workspace_access.list_mine --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.workspace_access.list_mine",
    "input": {
      "org_id": "org_example",
      "app_id": "app_topolo_campaigns"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Workspace access fetched",
  "data": {
    "organizationId": "org_example",
    "appId": "app_topolo_campaigns",
    "accessMode": "restricted",
    "canManageAll": false,
    "resources": []
  },
  "timestamp": "2026-10-02T18:24:03.955Z"
}

Valid platform authority reads another organization boundary

Input · payload.json:

{
  "org_id": "org_example",
  "app_id": "app_topolo_campaigns"
}

CLI:

topolo actions validate app_topolo_auth.workspace_access.list_mine --data @payload.json --json
topolo actions plan app_topolo_auth.workspace_access.list_mine --data @payload.json --json
topolo actions call app_topolo_auth.workspace_access.list_mine --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.workspace_access.list_mine",
    "input": {
      "org_id": "org_example",
      "app_id": "app_topolo_campaigns"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Workspace access fetched",
  "data": {
    "organizationId": "org_example",
    "appId": "app_topolo_campaigns",
    "accessMode": "all",
    "canManageAll": true,
    "resources": [
      {
        "id": "ws_fixture_one",
        "appId": "app_topolo_campaigns",
        "organizationId": "org_example",
        "name": "Campaigns",
        "avatar": {
          "kind": "preset",
          "presetId": "orbit"
        },
        "slug": "campaigns",
        "status": "active",
        "isDefault": false,
        "ownerUserId": "usr_owner",
        "createdByUserId": null,
        "createdAt": 1790965443,
        "updatedAt": 1790965443,
        "archivedAt": null,
        "accessRole": "organization_admin",
        "accessLevel": "admin"
      },
      {
        "id": "ws_fixture_two",
        "appId": "app_topolo_campaigns",
        "organizationId": "org_example",
        "name": "Research",
        "avatar": {
          "kind": "preset",
          "presetId": "orbit"
        },
        "slug": "research",
        "status": "active",
        "isDefault": false,
        "ownerUserId": "usr_other_owner",
        "createdByUserId": null,
        "createdAt": 1790965443,
        "updatedAt": 1790965443,
        "archivedAt": null,
        "accessRole": "organization_admin",
        "accessLevel": "admin"
      }
    ]
  },
  "timestamp": "2026-10-02T18:24:03.956Z"
}

Recipient projection contains the granted workspace and read level

Input · payload.json:

{
  "org_id": "org_example",
  "app_id": "app_topolo_campaigns"
}

CLI:

topolo actions validate app_topolo_auth.workspace_access.list_mine --data @payload.json --json
topolo actions plan app_topolo_auth.workspace_access.list_mine --data @payload.json --json
topolo actions call app_topolo_auth.workspace_access.list_mine --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.workspace_access.list_mine",
    "input": {
      "org_id": "org_example",
      "app_id": "app_topolo_campaigns"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Workspace access fetched",
  "data": {
    "organizationId": "org_example",
    "appId": "app_topolo_campaigns",
    "accessMode": "restricted",
    "canManageAll": false,
    "resources": [
      {
        "id": "ws_fixture_one",
        "appId": "app_topolo_campaigns",
        "organizationId": "org_example",
        "name": "Campaigns",
        "avatar": {
          "kind": "preset",
          "presetId": "orbit"
        },
        "slug": "campaigns",
        "status": "active",
        "isDefault": false,
        "ownerUserId": "usr_owner",
        "createdByUserId": null,
        "createdAt": 1790965443,
        "updatedAt": 1790965443,
        "archivedAt": null,
        "accessRole": "member",
        "accessLevel": "read"
      }
    ]
  },
  "timestamp": "2026-10-02T18:24:03.961Z"
}

Recipient no longer sees the revoked workspace

Input · payload.json:

{
  "org_id": "org_example",
  "app_id": "app_topolo_campaigns"
}

CLI:

topolo actions validate app_topolo_auth.workspace_access.list_mine --data @payload.json --json
topolo actions plan app_topolo_auth.workspace_access.list_mine --data @payload.json --json
topolo actions call app_topolo_auth.workspace_access.list_mine --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.workspace_access.list_mine",
    "input": {
      "org_id": "org_example",
      "app_id": "app_topolo_campaigns"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Workspace access fetched",
  "data": {
    "organizationId": "org_example",
    "appId": "app_topolo_campaigns",
    "accessMode": "restricted",
    "canManageAll": false,
    "resources": []
  },
  "timestamp": "2026-10-02T18:24:03.963Z"
}

Previous owner without retained access has no workspace projection

Input · payload.json:

{
  "org_id": "org_example",
  "app_id": "app_topolo_campaigns"
}

CLI:

topolo actions validate app_topolo_auth.workspace_access.list_mine --data @payload.json --json
topolo actions plan app_topolo_auth.workspace_access.list_mine --data @payload.json --json
topolo actions call app_topolo_auth.workspace_access.list_mine --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.workspace_access.list_mine",
    "input": {
      "org_id": "org_example",
      "app_id": "app_topolo_campaigns"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Workspace access fetched",
  "data": {
    "organizationId": "org_example",
    "appId": "app_topolo_campaigns",
    "accessMode": "restricted",
    "canManageAll": false,
    "resources": []
  },
  "timestamp": "2026-10-02T18:24:03.965Z"
}

Verify the result

• Use only returned data.resources[].id in this application/organization. Confirm the expected accessRole/accessLevel and do not infer access to a workspace absent from the projection.

• Verify a request as the intended principal through the owning application; discovery does not prove every application operation is allowed.

Errors and recovery

Explicit Personal context is refused despite stale orgId

Captured local refusal · HTTP 403:

{
  "input": {
    "org_id": "org_example",
    "app_id": "app_topolo_campaigns"
  },
  "response": {
    "success": false,
    "error": {
      "message": "Workspace access is limited to the active organization",
      "code": "FORBIDDEN",
      "details": null,
      "timestamp": "2026-10-02T18:24:03.963Z"
    }
  }
}

Conflicting organization aliases are refused

Captured local refusal · HTTP 403:

{
  "input": {
    "org_id": "org_example",
    "app_id": "app_topolo_campaigns"
  },
  "response": {
    "success": false,
    "error": {
      "message": "Workspace access is limited to the active organization",
      "code": "FORBIDDEN",
      "details": null,
      "timestamp": "2026-10-02T18:24:03.963Z"
    }
  }
}

Anonymous workspace discovery is refused

Captured local refusal · HTTP 401:

{
  "input": {
    "org_id": "org_example",
    "app_id": "app_topolo_campaigns"
  },
  "response": {
    "success": false,
    "error": {
      "message": "Access token required",
      "code": "AUTH_ERROR",
      "details": null,
      "timestamp": "2026-10-02T18:24:03.963Z"
    }
  }
}

Published recovery guidance

• VALIDATION_ERROR (HTTP 400): Correct the reported fields and use an existing active same-organization app member. Directory candidates alone do not prove eligibility.

• AUTH_ERROR (HTTP 401): Verify the intended authenticated identity and refresh an expired token if necessary. Do not change credential context automatically.

• FORBIDDEN (HTTP 403): Check consistent active organization context and exact workspace management authority. Personal/conflicting context is refused even with stale org metadata or platform roles.

• NOT_FOUND (HTTP 404): Refresh canonical workspace/member discovery. An already revoked member grant is absent; do not fabricate a stored grant.

• CONFLICT (HTTP 409): Read current owner and grants before reviewing any new decision. Do not grant/revoke the owner as a member or blindly repeat a completed/partial transfer.

• SERVER_ERROR (HTTP 500): Read current owner and member grants before retrying. Ownership may already have changed. Preserve a partial owner/grant state for authorized repair when customer actions cannot complete cleanup.

Recovery boundaries

Read-only. Correct the intended context through authorized identity discovery and preserve any denial; refresh after a legitimate access change.

Discovery and evidence

This record belongs to app_topolo_auth. Local tests prove real canonical workspace/grant SQL and handler responses with simulated identity, directory lookup, memberships and application assignment. They do not prove recipient sign-in, invitation delivery, owning-application resource enforcement, live permissions, deployment or production completion.