Admin

What It Is

Topolo Admin is the operator-facing administrative UI for platform-wide organization, user, service, permission, and audit workflows.

Automation workflows

Examples below are source-reviewed illustrations of input and expected behavior. They were not executed and are not captured responses. IDs are placeholders to replace with identifiers discovered in the selected context. Dates are illustrative. Successful persistence, notification requests, provider connection and recipient delivery require separate verification.

Authorization and selected context

Verify the intended environment, signed-in identity and organization, then inspect the credential-scoped Admin action. The widget takes an empty input object; its effective administrator role and organization or platform metric scope must be checked separately. A schema-valid request is not an access grant. Verify the returned widget state, retain request identifiers and keep credentials out of documentation.

Administrator access

The Admin widget is a read-only summary for eligible administrators. Runtime authorization requires organization owner, super_admin or admin access, or qualifying platform_admin/platform_super_admin membership in the admin organization. A dashboard:read permission entry alone does not grant that role. Platform metrics and organization-visible metrics have different scope; do not infer platform access from an organization role. The published action accepts an empty object and has no workspace selector in its input. Read the returned widget state and scope; missing or unavailable metrics are not proof that the underlying count is zero.

Illustrative inputs and expected behavior

Read the Admin summary

Action: app_topolo_admin.widget.get · Inspect contract

Illustrative input; replace discovered identifiers before any authorized call.

{}

Expected behavior: Returns the widget envelope or an access refusal for the authenticated administrator. Inspect widget scope and state; no metric values are asserted.

Action index

Inspect each current action before use; this workflow index does not replace its input/output contract.

Architecture

The app is a React-based browser surface that depends on Topolo Auth for identity and authorization while presenting role-aware admin workflows for platform-admin and organization-admin users. Legacy Admin routes for developer review queues and support now act only as handoff screens into their owning applications.

Runtime Surfaces

The primary host is https://admin.topolo.app. Development and staging mirrors run at https://admin.topolo.dev and https://admin.stg.topolo.us.

API Reference

Topolo Admin is primarily a UI surface over Auth-backed admin routes. Use the current action reference together with the Auth references for the current runtime and admin API families.

Authenticated admins can set a user password directly from the admin UI without using the public email-token recovery flow. Eligible admins can delete users directly from the admin UI. Standard deletion removes access and hides the user from normal admin reads, while super-admin permanent deletion is reserved for full erase cases. Organization deletion is a soft-delete workflow that immediately suspends org-user access, blocks org-scoped service authorization, and keeps the org available for later restore or retention-based purge. Super admins can also surface deleted organizations in the admin UI and restore them when needed. Org admins can create organization-specific custom roles, start them from an existing org role template, decide which applications belong to each role, and manage each role's per-application permission bundle inside their own organization rather than relying on one fixed global role set for every tenant. Org admins can also manage per-user launchable application access within the set of apps already enabled for the organization. Apps included for the whole org remain enabled for everyone, while seat-based apps can be assigned or unassigned per user only when the org still has available seats. Auth remains the source of truth for seat usage and role-based preset suggestions. Super admins can also manage assignments from the application side by opening a service and assigning or revoking it for selected organizations, every active organization, selected eligible users, or every eligible user. User-level assignment remains bounded by the organization's app entitlement. Organization service assignment separates launchable applications from technical services such as APIs, runtimes, and internal support services using Auth catalog metadata.

Auth and Permissions

Topolo Admin uses Auth-issued bearer or session context and enforces role-based access for platform-admin and org-admin operations. Platform-wide actions are reserved to Auth platform_super_admin and platform_admin users in the admin organization; org-scoped super_admin users stay scoped to their own org in the browser UI. Browser login URL construction and callback-code redemption run through the shared Topolo Auth client rather than Admin-owned handoff or exchange paths. That org-scoped tier remains elevated over normal members: same-org owners, org super admins, and admins can still manage organization settings, user security, sessions, and user-level permission workflows without receiving platform-wide controls. The browser keeps a same-tab Auth token restore by default after sign-in and refresh, so a normal reload should return to the Admin workspace rather than appearing signed out while cookie refresh catches up.

Data Ownership

Topolo Admin owns the administrative browser experience. Topolo Auth remains the source of truth for users, orgs, services, permissions, and audit records. That includes per-user application access overrides layered on top of org-level app access. It also includes the app-centric assignment UI; Admin owns target selection and bulk grant/revoke actions while Auth owns persisted organization-service relationships and user-service access evaluation. Developer review queues now live in Topolo Developers, and support workflow now lives in Topolo Support.

Mobile Experience

The checked-in mobile experience contract is approved in web mode. Its fallback route is /dashboard, its offline policy is not specified in this guide, and it requires organization context.

Published permissions: none.

• No native routes are published yet.

The native clients consume this manifest as an explicit rendering contract. A web mode record intentionally opens the product web experience; native_capability publishes the listed native routes and actions. Do not infer unlisted native behavior.

Deployments

Topolo Admin deploys as a browser application that fronts the centralized Auth admin APIs.

Failure Modes

• stale admin role or session context
• UI drift from current Auth admin route families
• org-scoped actions incorrectly treated as platform-wide actions

Debugging

Start with the current action reference for the current host and service metadata, then verify the corresponding Auth admin route family.

Use It

Open Topolo Admin for the human product surface. Use the current Auth API reference for the supported automation contracts.

Discover the credential-scoped automation surface before making an API call:

topolo services --query topolo-admin --json
topolo actions --service topolo-admin --json
topolo actions capabilities --service topolo-admin --json

Choose an action, inspect it with topolo actions get <action-id> --json, then validate and plan a published example. The Agent Actions reference exposes the same public schemas, effects, examples, verification, and recovery guidance.

Example workflow:

1. Confirm the active identity and organization with topolo whoami --json.
2. Discover Topolo Admin and select one published action rather than guessing a route.
3. Inspect its input/output schemas and published example.
4. Validate and plan the exact payload; obtain confirmation for a mutation.
5. Execute and perform every published verification step.

Getting Started

The first-run checklist keeps progress in Topolo Auth for the signed-in user, organization and application. If progress cannot be loaded, use Retry to restore the saved checklist. Step navigation and Skip for now wait for a successful progress save; a failed save leaves the action available to retry. Switching organizations loads that organization's progress without applying a late response from the previous organization.

Admin resolves the Auth service origin through the shared Topolo app shell, including builds without the legacy Vite Auth URL.

Change Log / Verification

• Verified first-run load recovery, save-before-navigation, dismissal and organization scope on 2026-10-04 against source 0fa44c2924ade3e94def01abb60d4151d106f528, using the published shared onboarding component and a 100% coverage ratchet for the host page.

• Verified the web mobile experience contract and its 0 published route(s) against apps/TopoloAdmin origin/staging 8a54b6ffb422 on 2026-07-27.

• Reconciled workspace verification on 2026-06-28 against apps/TopoloAdmin commits through bfa6bfd; reviewed 10 commits since 2026-06-26, including bfa6bfd chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 62cb882 Wait for lazy Admin landing in bootstrap test; 3ca0766 Split Admin startup shell bundle; 9ad7501 Adopt canonical Topolo typography.

• Corrected authenticated Admin shell content padding on 2026-04-28 so audit log details and sibling workspace pages use the same tighter spacing from the shared sidebar and top chrome.

• Enabled same-tab browser session restore by default on 2026-04-23 so Admin reloads remain signed in after successful Auth handoff or refresh.

• Recast Admin onto the explicit platform-role model on 2026-04-24 so only Auth platform_super_admin and platform_admin users in the admin org render platform-admin actions and global datasets.

• Restored elevated org-admin handling on 2026-04-24 so same-org owners, org super admins, and admins keep org-scoped settings, security, session, and permission-management access after platform-only UI is removed.

• Corrected app-centric assignment management on 2026-04-22 so service rows navigate through the Admin router and assigned organizations or users can be selected for revoke actions.

• Segmented organization service assignment by service surface on 2026-04-23 so application access and technical capability access are easier to manage separately.

• Added app-centric organization and user assignment management on 2026-04-22.

• Delegated Admin login URL construction and callback-code redemption to the shared Topolo Auth client on 2026-04-18.

• Re-homed developer review queues and support workflow out of Admin on 2026-04-13 so the old Admin routes now hand operators off to the owning applications instead of fronting duplicate queue logic

• Added organization-scoped custom-role management on 2026-04-10 so org admins can create org-specific roles and tailor each role's service permissions inside the admin UI

• Clarified org-role bundle management on 2026-04-10 so org admins can explicitly add or remove applications from a role and seed new custom roles from existing org-role templates before tailoring permissions

• Converted per-user application access to the seat-assignment model on 2026-04-26 so org admins can assign or unassign seat-based apps inside their own org while org-included apps remain enabled for everyone.

• Added per-user application access management on 2026-04-10 so org admins can narrow which org-enabled applications a user can launch and apply role-based preset suggestions from Auth

• Corrected the Admin browser favicon rollout on 2026-04-07 so the live application now points at the new brand icon set instead of continuing to rely on the older cached ICO path

• Added canonical Topolo Admin coverage and retired repo-local admin docs on 2026-03-30

• Verified the direct admin password-set workflow on 2026-03-31

• Verified the admin user-delete workflow and soft-delete visibility rules on 2026-03-31

• Verified the distinction between soft delete and permanent user purge on 2026-03-31

• Verified that org soft-delete immediately suspends org-user access and hides deleted orgs from normal Admin reads on 2026-03-31

• Verified that super admins can surface and restore soft-deleted organizations on 2026-03-31

• Verified that the Admin add-user form starts with blank email and password fields instead of inheriting login autofill on 2026-04-03