List organizations

Outcome

Read the organization directory as verified platform authority.

Full examples below were captured from isolated actual Auth handlers and repository SQL with disclosed simulations.

Before you start

• Verify the intended credential identity and pinned context; discover the exact organization id and published target authority. Display labels and synthetic fixture ids do not authorize a live call.

• Keep directory user counts, computed membership seats and application-resource authority separate.

Discover the authorized organization

topolo whoami --json
topolo context ls --json
topolo actions get app_topolo_auth.organizations.list --detail --json

Organization directory discovery itself requires platform authority. An ordinary manager must use the organization already resolved from its credential context; directory refusal does not justify switching context.

Input fields

Response fields

A success contains success=true, message, data and an ISO timestamp. Refusals contain success=false and error instead. Directory/detail responses use camelCase projections; export preserves selected raw snake_case fields and JSON text.

Listing the platform directory requires verified platform authority. Ordinary organization ownership is refused with HTTP 401 AUTH_ERROR; this refusal alone does not establish expired OAuth.

organizations contains undeleted rows by default, including inactive rows. includeDeleted=true also includes soft-deleted organizations. Rows are ordered by createdAt descending; equal timestamps do not guarantee stable ordering.

pagination reports the requested page and bounded limit, totalCount/totalPages and hasNextPage/hasPrevPage. Empty results on a later page do not prove there are no organizations. Directory and count queries are separate and are not a transactional snapshot.

userCount counts distinct member user ids whose user record is not deleted; it includes service and agent identities and does not require an active membership. serviceCount counts active organization-service relationships. Neither number is the billable human seat count.

settings is parsed stored JSON; malformed JSON causes a server error. isActive reflects status=active only. Timestamps are stored epoch seconds. Supporting count-query failure can use the repository membership-count path, so anomalous totals require maintainer investigation rather than inferred fleet completeness.

Worked examples

Every identifier, address and stored record below is synthetic. Resolve live identifiers and runtime authority before validating and planning the unchanged read. The CLI/MCP connection supplies its own credential; fixture token scenarios are not input fields. Empty fixture collections do not prove production feature coverage or provider parity.

Platform authority lists undeleted organizations with page metadata

Input · payload.json:

{}

CLI:

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

MCP read after topolo_validate_action and topolo_plan_action on the same input:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.organizations.list",
    "input": {}
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Organizations fetched successfully",
  "data": {
    "organizations": [
      {
        "id": "org_read_other",
        "name": "org_read_other",
        "slug": "org_read_other",
        "domain": null,
        "logoUrl": null,
        "settings": {
          "theme": "fixture"
        },
        "isActive": false,
        "status": "inactive",
        "userCount": 0,
        "serviceCount": 0,
        "createdAt": 3,
        "updatedAt": 3
      },
      {
        "id": "org_read_fixture",
        "name": "org_read_fixture",
        "slug": "org_read_fixture",
        "domain": null,
        "logoUrl": null,
        "settings": {
          "theme": "fixture"
        },
        "isActive": true,
        "status": "active",
        "userCount": 4,
        "serviceCount": 0,
        "createdAt": 1,
        "updatedAt": 1
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "totalCount": 2,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPrevPage": false
    }
  },
  "timestamp": "2026-10-03T00:00:00.000Z"
}

Explicit deleted inclusion and a bounded second page

Input · payload.json:

{
  "page": 2,
  "limit": 1,
  "includeDeleted": true
}

CLI:

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

MCP read after topolo_validate_action and topolo_plan_action on the same input:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.organizations.list",
    "input": {
      "page": 2,
      "limit": 1,
      "includeDeleted": true
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Organizations fetched successfully",
  "data": {
    "organizations": [
      {
        "id": "org_read_deleted",
        "name": "org_read_deleted",
        "slug": "org_read_deleted",
        "domain": null,
        "logoUrl": null,
        "settings": {
          "theme": "fixture"
        },
        "isActive": false,
        "status": "deleted",
        "userCount": 0,
        "serviceCount": 0,
        "createdAt": 2,
        "updatedAt": 2
      }
    ],
    "pagination": {
      "page": 2,
      "limit": 1,
      "totalCount": 3,
      "totalPages": 3,
      "hasNextPage": true,
      "hasPrevPage": true
    }
  },
  "timestamp": "2026-10-03T00:00:00.000Z"
}

An out-of-range page is empty while totalCount remains authoritative

Input · payload.json:

{
  "page": 9,
  "limit": 1
}

CLI:

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

MCP read after topolo_validate_action and topolo_plan_action on the same input:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.organizations.list",
    "input": {
      "page": 9,
      "limit": 1
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Organizations fetched successfully",
  "data": {
    "organizations": [],
    "pagination": {
      "page": 9,
      "limit": 1,
      "totalCount": 2,
      "totalPages": 2,
      "hasNextPage": false,
      "hasPrevPage": true
    }
  },
  "timestamp": "2026-10-03T00:00:00.000Z"
}

Verify the result

• Follow pagination.hasNextPage using the same limit/filter; retain ids and report the observation scope rather than claiming a consistent snapshot.

Errors and recovery

Missing credential is refused

Input:

{}

Captured local refusal · HTTP 401:

{
  "success": false,
  "error": {
    "message": "Access token required",
    "code": "AUTH_ERROR",
    "details": null,
    "timestamp": "2026-10-03T00:00:00.000Z"
  }
}

Ordinary organization ownership cannot list every organization

Input:

{}

Captured local refusal · HTTP 401:

{
  "success": false,
  "error": {
    "message": "Platform admin access required",
    "code": "AUTH_ERROR",
    "details": null,
    "timestamp": "2026-10-03T00:00:00.000Z"
  }
}

Published recovery guidance

• AUTH_ERROR (HTTP 401): Verify the same pinned credential and exact refusal. For directory/detail/export this code also reports denied authority; do not change context or assume expiry.

• SERVER_ERROR (HTTP 500): Preserve sanitized request/status evidence for an authorized Auth maintainer. These reads do not write; after the underlying store/parser issue is resolved, review a fresh read of the same target.

Recovery boundary

This read has no rollback. Keep the same discovered organization and credential context; respect authority refusal and preserve sanitized evidence for store failures. Re-read only after the underlying issue is resolved.

Discovery and evidence

Actual isolated organization handlers and repository SQL; no live identity, membership, billing or export was changed.

Real: Organization read/billing/privacy handlers; Organization directory/service and seat summary SQL; Portable export field selection and database routing; Canonical migration-created tables and SQLite engine; Response serialization and permission helpers. Simulated: Verified token identities and hydrated membership lookup; Empty application icon catalog; Clock, synthetic records and deliberate malformed settings; All split bindings co-located in isolated SQLite; no multi-D1 provider parity. No live organization, identity, membership, export, billing or seat changed.