Get organization

Outcome

Read organization details by organization id.

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.get --detail --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.

The exact organization is readable by verified platform authority or an owner, super_admin or admin role bound to that exact organization in the verified token. This read does not grant membership, switch a pinned credential or authorize any application mutation.

Deleted organizations are omitted unless includeDeleted=true and the caller has platform authority. An ordinary manager cannot use that flag to read a deleted organization. Missing/omitted deleted records return HTTP 404 NOT_FOUND.

data is the organization itself with parsed settings, planType, userCount and enriched granted services. userCount counts non-deleted users across membership rows, including agent/service identities; it is not billableSeatCount. Resolve exact services/resources and their target permissions separately.

services can be empty when nothing is granted. The local fixture uses a deliberately empty icon catalog and no granted service; it does not prove live service rendering, catalog enrichment or application entitlement parity.

settings is parsed JSON and timestamps are stored epoch seconds. Malformed settings produce HTTP 500 SERVER_ERROR. Keep the same target and preserve sanitized request evidence; do not infer an authentication refresh or fabricate empty settings.

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.

Organization owner reads its details and currently granted services

Input · payload.json:

{
  "orgId": "org_read_fixture"
}

CLI:

topolo actions validate app_topolo_auth.organizations.get --data @payload.json --json
topolo actions plan app_topolo_auth.organizations.get --data @payload.json --json
topolo actions call app_topolo_auth.organizations.get --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.get",
    "input": {
      "orgId": "org_read_fixture"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Organization fetched successfully",
  "data": {
    "id": "org_read_fixture",
    "name": "org_read_fixture",
    "slug": "org_read_fixture",
    "domain": null,
    "logoUrl": null,
    "settings": {
      "theme": "fixture"
    },
    "planType": "basic",
    "isActive": true,
    "status": "active",
    "userCount": 4,
    "createdAt": 1,
    "updatedAt": 1,
    "services": []
  },
  "timestamp": "2026-10-03T00:00:00.000Z"
}

Only platform authority includes a soft-deleted organization

Input · payload.json:

{
  "orgId": "org_read_deleted",
  "includeDeleted": true
}

CLI:

topolo actions validate app_topolo_auth.organizations.get --data @payload.json --json
topolo actions plan app_topolo_auth.organizations.get --data @payload.json --json
topolo actions call app_topolo_auth.organizations.get --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.get",
    "input": {
      "orgId": "org_read_deleted",
      "includeDeleted": true
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "Organization fetched successfully",
  "data": {
    "id": "org_read_deleted",
    "name": "org_read_deleted",
    "slug": "org_read_deleted",
    "domain": null,
    "logoUrl": null,
    "settings": {
      "theme": "fixture"
    },
    "planType": "basic",
    "isActive": false,
    "status": "deleted",
    "userCount": 0,
    "createdAt": 2,
    "updatedAt": 2,
    "services": []
  },
  "timestamp": "2026-10-03T00:00:00.000Z"
}

Verify the result

• Match data.id to the authorized input and interpret services/userCount separately from target permissions and billable seats.

Errors and recovery

Omitted deleted inclusion does not find a soft-deleted organization

Input:

{
  "orgId": "org_read_deleted"
}

Captured local refusal · HTTP 404:

{
  "success": false,
  "error": {
    "message": "Organization not found",
    "code": "NOT_FOUND",
    "details": null,
    "timestamp": "2026-10-03T00:00:00.000Z"
  }
}

Missing credential is refused

Input:

{
  "orgId": "org_read_fixture"
}

Captured local refusal · HTTP 401:

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

A foreign organization administrator cannot read this organization

Input:

{
  "orgId": "org_read_fixture"
}

Captured local refusal · HTTP 401:

{
  "success": false,
  "error": {
    "message": "Access denied: You can only view your own organization",
    "code": "AUTH_ERROR",
    "details": null,
    "timestamp": "2026-10-03T00:00:00.000Z"
  }
}

Malformed stored settings fail the current detail parser

Input:

{
  "orgId": "org_read_fixture"
}

Captured local refusal · HTTP 500:

{
  "success": false,
  "error": {
    "message": "Failed to fetch organization: Expected property name or '}' in JSON at position 1 (line 1 column 2)",
    "code": "SERVER_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.

• NOT_FOUND (HTTP 404): Rediscover the exact organization under the same authorized context. For detail, respect the platform-only deleted inclusion rule.

• 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.