Topolo Docs Topolo Platform
Open workspace

Read the Admin operations widget — Admin

Reads a v3 widget and requests Auth aggregate statistics using the original caller authorization. It changes no Admin records.

Read the Admin operations widget

Reads a v3 widget and requests Auth aggregate statistics using the original caller authorization. It changes no Admin records.

Outcome and boundaries

Reads a v3 widget and requests Auth aggregate statistics using the original caller authorization. It changes no Admin records.

Runtime access requires an organization owner/admin/super_admin or qualified platform-admin membership. Empty, unavailable and role-denied states must not be interpreted as zero users or organizations.

Before you start

  • Confirm the intended environment and current credential organization using whoami; discover the exact application/action before any call.
  • Required application permission: app_topolo_admin.dashboard:read. Catalog discoverability is not permission to execute.
  • Current resource catalog exposes no Admin action resource alias; retain the authenticated organization/runtime role decision.
  • All worked cases in this guide are hypothetical source-reviewed illustrations; no business action, live fixture, customer data or provider request was executed.

Discover the intended identifiers

  • Confirm the current human/session identity and organization. Inspect Admin widget.get and its runtime permission decision; role display alone does not prove access.
  • Current Admin resource metadata publishes no action resource alias. Do not invent a workspace/organization resource binding to bypass its runtime role gate.

Action: app_topolo_admin.widget.get · GET /api/widget.

Input fields

No input fields. Send {}. Any published resource context remains separate from this object.

Safe call sequence

Write the reviewed input to payload.json; fixture identifiers below are unusable examples. Validate before planning, bind the discovered resource separately, and execute only within actual authority.

topolo actions validate app_topolo_admin.widget.get --data @payload.json --json
topolo actions plan app_topolo_admin.widget.get --data @payload.json --json

A published read can use topolo actions call with the same discovered resource and input. This guide does not invoke it.

Worked cases

The two Admin widget envelopes below are explicitly partial structural illustrations, not complete handler responses. They show required v3 fields and the empty/ready state distinction while omitting source contribution metadata and metric values. Translated labels and metric counts were not captured. Do not treat an empty or ready illustration as evidence of caller access, successful Auth statistics, zero users or full source/output conformance.

Every response below is synthetic and source-reviewed, not captured. HTTP status and body are explained independently; a structurally valid body alone never proves successful execution. Middleware may add a different error envelope.

Illustrative empty organization overview · HTTP 200

Input:

{}

Illustrative response:

{
  "success": true,
  "contractVersion": "3.0.0",
  "appId": "app_topolo_admin",
  "serviceName": "Admin",
  "generatedAt": "2026-10-20T00:00:00.000Z",
  "widgets": [
    {
      "id": "admin.organization-overview",
      "version": "1.0.0",
      "type": "stats",
      "presentation": {
        "title": "Illustrative overview"
      },
      "resource": {
        "resourceType": "organization",
        "resourceId": "org_example",
        "requiredPermissions": [
          "dashboard:read"
        ]
      },
      "state": {
        "status": "empty",
        "observedAt": "2026-10-20T00:00:00.000Z"
      },
      "refresh": {
        "intervalSeconds": 60
      },
      "configuration": {
        "fields": []
      },
      "drilldowns": [],
      "controls": [],
      "localization": {
        "locale": "en"
      },
      "accessibility": {
        "label": "Illustrative overview"
      }
    }
  ]
}

Illustrative ready state · HTTP 200

Input:

{}

Illustrative response:

{
  "success": true,
  "contractVersion": "3.0.0",
  "appId": "app_topolo_admin",
  "serviceName": "Admin",
  "generatedAt": "2026-10-20T00:00:00.000Z",
  "widgets": [
    {
      "id": "admin.organization-overview",
      "version": "1.0.0",
      "type": "stats",
      "presentation": {
        "title": "Illustrative overview"
      },
      "resource": {},
      "state": {
        "status": "ready",
        "observedAt": "2026-10-20T00:00:00.000Z"
      },
      "refresh": {
        "intervalSeconds": 60
      },
      "configuration": {
        "fields": []
      },
      "drilldowns": [],
      "controls": [],
      "localization": {
        "locale": "en"
      },
      "accessibility": {
        "label": "Illustrative overview"
      }
    }
  ]
}

Synthetic structural example only; no concrete user count or caller entitlement is asserted.

Declared runtime permission refusal · HTTP 403

Input:

{}

Illustrative response:

{
  "error": "permission_denied"
}

Illustrative refusal code from catalog; the exact middleware envelope was not captured.

Verify the outcome

  • Check contractVersion 3.0.0, appId app_topolo_admin, widget state and organization resource. Platform versus organization metrics depend on verified membership; counts are only the scope returned.

Refusals and recovery

  • HTTP 401 authentication_required: Correct the named input or retain the authoritative refusal in the same context.
  • HTTP 403 permission_denied: Correct the named input or retain the authoritative refusal in the same context.
  • HTTP 503 dependency_unavailable: Correct the named input or retain the authoritative refusal in the same context.

Read-only. Resolve the actual authentication/runtime-role refusal with the legitimate access owner; do not switch to an administrator credential as a fallback.

Source and catalog limits

The action catalog sourceRevision is a manifest marker (topolo.app.json), not a commit. This draft pins the current main source independently and does not infer loaded-runtime association.

Exact schemas and provenance

Input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Output schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "const": true
    },
    "contractVersion": {
      "type": "string",
      "const": "3.0.0"
    },
    "appId": {
      "type": "string",
      "minLength": 1
    },
    "serviceName": {
      "type": "string",
      "minLength": 1
    },
    "generatedAt": {
      "type": "string",
      "minLength": 1
    },
    "widgets": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1
          },
          "version": {
            "type": "string",
            "minLength": 1
          },
          "type": {
            "type": "string",
            "enum": [
              "stats",
              "chart",
              "activity",
              "notifications",
              "actions"
            ]
          },
          "presentation": {
            "type": "object",
            "additionalProperties": true
          },
          "resource": {
            "type": "object",
            "additionalProperties": true
          },
          "state": {
            "type": "object",
            "additionalProperties": true
          },
          "refresh": {
            "type": "object",
            "additionalProperties": true
          },
          "configuration": {
            "type": "object",
            "additionalProperties": true
          },
          "drilldowns": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "controls": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "localization": {
            "type": "object",
            "additionalProperties": true
          },
          "accessibility": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "id",
          "version",
          "type",
          "presentation",
          "resource",
          "state",
          "refresh",
          "configuration",
          "drilldowns",
          "controls",
          "localization",
          "accessibility"
        ],
        "additionalProperties": true
      }
    },
    "workspace": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                }
              ]
            },
            "name": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "name"
          ],
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ]
    },
    "workspaces": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name"
        ],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "success",
    "contractVersion",
    "appId",
    "serviceName",
    "generatedAt",
    "widgets"
  ],
  "additionalProperties": true
}

Reviewed immutable source: TopoloAdmin@5583704fea130a910034a3bfca27e941e95cad72, apps/api/src/widget.ts. Fresh production catalog was read on 2026-10-20. Its publication metadata is not proof that this source is loaded. Output examples are not widened or rewritten to force schema success; the accompanying validation record classifies exact success, refusal, no-body and structural-schema limits.

Local input rejection example

This deliberately invalid input belongs to a pure schema check; it is never a planned or executed request. The closed action input schema must reject the extra field. It has no HTTP status or server response.

{
  "__unsupported_field": true
}

The hidden companion labels this as ILLUSTRATIVE_LOCAL_SCHEMA_CHECK; its validation representation is not an action output.

Published output validation limits

Current published output qualification: the output schema rejects the empty-object, partial-success-marker, partial-data-object and refusal-body probes. A schema-valid success body still does not establish execution, live permission, selected context or a provider outcome.

These observations come from pure checks of the exact published schema; they are not server responses or production captures.