Superadmin Dashboard — Overview

The Superadmin dashboard is the platform operator's control plane: it manages every Organization, the global default config/pricing, telephony providers + SIP trunks + number pool, OAuth clients, benchmarks, provider capacity, concurrency, and cross-org bug reports — all above the tenant boundary.

No screenshots exist for this dashboard. It is documented from code: the sidebar comes from app/src/layouts/SuperAdminLayout.tsx, routes from the /superadmin/* group in app/src/routes.tsx, and APIs from the backend route/controller files. Any UI-layout claim not confirmable from code is tagged > ⚠️ Unverified.

Architecture Overview

How Access Is Decided (Step-by-Step)

1. Route role gate (frontend). app/src/routes.tsx wraps the superadmin route group in <ProtectedRoute allowedRoles={['superadmin']}>. Only a superadmin reaches /superadmin/*. Unlike the admin/customer dashboards, SA menu items are not feature-gated — a superadmin sees the whole control plane.
2. Backend middleware chain. Nearly every SA API runs verifyJwt → requireRole("superadmin") (no requireOrg — the superadmin operates across all orgs). Two exceptions: the Superadmins setup router (superadmin-setup.routes.ts) is guarded by the SUPERADMIN_API_SECRET header via verifyWebhookSecret rather than a JWT, and benchmarks use requireFeature("benchmark") where the superadmin bypasses the entitlement check.

Jargon: Superadmin = the Oktivo platform operator (above every Organization). Provider registry = the catalog of AI model providers (STT/TTS/LLM) and their capabilities. Provider capacity = concurrent-call limits negotiated with telephony/AI providers. SIP trunk = the signaling path between Oktivo (LiveKit) and a telephony carrier. See Feature Entitlements & Bundles, SIP Trunk Overview, and Concurrency Management.

Sidebar Menu → What It Does

⚠️ Unverified — the order below mirrors the navItems array in SuperAdminLayout.tsx; there is no screenshot to confirm the rendered layout.

Menu item	Route	What it manages
Dashboard	/superadmin/dashboard	Platform-wide KPI landing
Organizations	/superadmin/organizations	Create/list/edit/delete orgs
Tickets	/superadmin/tickets	Cross-org helpdesk view
Superadmins	/superadmin/superadmins	Manage superadmin users
System Config	/superadmin/system-config	Global default presets/voices/pricing
Provider Registry	/superadmin/provider-registry	AI provider/model registry entries
Number Management	/superadmin/providers	Telephony provider enablement per org
Credit Management	/superadmin/credits	Recharge orgs, platform credit summary
Per-Org Rates	/superadmin/org-rates	Per-org pricing overrides
OAuth Clients	/superadmin/oauth-clients	CRM OAuth client credentials
SIP Trunks	/superadmin/trunks	Create/sync SIP trunks
Phone Numbers	/superadmin/phone-numbers	Platform number pool
Benchmarks	/superadmin/benchmarks	Model benchmark runs
Provider Capacity	/superadmin/provider-capacity	Concurrent-call capacity per provider
Concurrency	/superadmin/concurrency	Platform concurrency allocation
Bug Reports	/superadmin/bug-reports	Cross-org bug reports
Account Settings	/superadmin/settings	Superadmin's own account

File Reference

File	Role	Mount prefix
app/src/layouts/SuperAdminLayout.tsx	Builds the SA sidebar	navItems
app/src/routes.tsx	Maps /superadmin/* paths, wraps group in ProtectedRoute allowedRoles=['superadmin']	SA route table
backend/.../routes/superadmin.routes.ts	Orgs, dashboard, superadmins list, credits, provider-capacity, system-config, concurrency, bug-reports	/superadmin
backend/.../routes/superadmin-provisioning.routes.ts	Provider registry (telephony), per-org enablement + rates, inventory	/superadmin/provisioning
backend/.../routes/superadmin-setup.routes.ts	Create/manage superadmin users (secret-guarded)	/setup
backend/.../routes/superadmin-oauth.routes.ts	CRM OAuth client CRUD	/superadmin/oauth-clients
backend/.../routes/systemConfig.routes.ts	Default presets/voices/versions	/api/v2/config
backend/.../routes/providerModelRegistry.routes.ts	AI provider/model registry	/api/config/provider-registry
backend/.../routes/orgConfigReplica.routes.ts	Per-org rate overrides (SA endpoints)	/api/org-config
backend/.../routes/benchmark.routes.ts	Benchmark CRUD + runs	/superadmin/benchmarks, /benchmarks
backend/.../routes/concurrency.routes.ts	SA concurrency routes	/superadmin/concurrency
backend/.../routes/telephony.routes.ts	SA SIP trunks + number pool	/superadmin/sip-trunks, /superadmin/phone-numbers

Data Model

The superadmin operates above the org boundary, reading/writing platform-wide collections plus per-org overrides. See Data Collections for full schemas.

API Endpoints

The overview has no endpoints of its own; role context comes from the auth session. Per-menu endpoints are enumerated in Superadmin Dashboard — Sections & APIs.

Current superadmin context

• Method: GET
• Path: /auth/me
• Auth: verifyJwt
• Response: 200 with the user, role superadmin, used by ProtectedRoute.

External Integrations

• Telephony providers / carriers — SIP Trunks + Number Management + Provider Capacity (LiveKit SIP, carrier APIs).
• AI model providers — Provider Registry + Benchmarks (STT/TTS/LLM vendors).
• CRM providers — OAuth Clients (external CRM OAuth).

Covered per-menu in Superadmin Dashboard.

How to Test (End-to-End)

1. Prerequisites: a superadmin account; backend + frontend running.
2. Log in as superadmin and confirm you land on /superadmin/dashboard (an admin/customer login must not reach /superadmin/*).
3. Open each menu item and confirm the landing API returns 200 across orgs (no requireOrg scoping).
4. Confirm the Superadmins management API rejects requests lacking the SUPERADMIN_API_SECRET header.

Troubleshooting

Symptom	Cause	Fix
/superadmin/* redirects to login	User is not role superadmin	Log in with a superadmin account
Superadmin CRUD returns 401	Missing SUPERADMIN_API_SECRET header (setup router)	Send the secret header; see superadmin-setup.routes.ts
Benchmarks blocked	requireFeature("benchmark") — superadmin should bypass	Verify the role is resolved as superadmin in the JWT
Cross-org data missing	Querying with an org-scoped token	Use a superadmin token (no requireOrg applies)