Superadmin Dashboard — Sections & APIs

Section-by-section reference for every Superadmin menu item: its route, the backend API it calls (method + path), the controller/service behind it, and the MongoDB collection(s) it writes.

No screenshots exist for this dashboard. Menu order and names come from app/src/layouts/SuperAdminLayout.tsx; routes from the /superadmin/* group in app/src/routes.tsx. UI-layout claims not confirmable from code are tagged > ⚠️ Unverified. See the Superadmin overview for role gating.

Architecture Overview

Most SA routes share router.use(verifyJwt, requireRole("superadmin")) in superadmin.routes.ts. Paths below show their mount prefix.

1. Dashboard — /superadmin/dashboard

Platform-wide KPI landing. Page: pages/superadmin/DashboardPage.tsx. Controller: superadmin.controller.ts.

• Platform dashboard → GET /superadmin/dashboard (getDashboard) — aggregates org/credit/usage counts (read-only).

⚠️ Unverified — the exact cards rendered are not confirmable from code alone.

2. Organizations — /superadmin/organizations

Create, list, edit, delete organizations. Controllers: superadmin.controller.ts, deletion.controller.ts, emailAuth.controller.ts.

Action	Method + Path	Handler	Collection
List orgs	GET /superadmin/organizations	listOrganizations	Organization (read)
Get org	GET /superadmin/organizations/:orgId	getOrganization	— (read)
Create org	POST /superadmin/organizations	createOrganization	Organization, User (admin)
Update org	PUT /superadmin/organizations/:orgId	updateOrganization	Organization
Delete org	POST /superadmin/organizations/:orgUID/delete	deleteOrganization	Organization (+ cascades)
Resend onboarding	POST /superadmin/resend-onboarding/:userUID	superadminResendOnboarding	EmailToken

3. Tickets — /superadmin/tickets

Cross-org helpdesk view. Page: pages/superadmin/TicketsPage.tsx. Uses the shared ticket API (ticket.routes.ts): GET /api/tickets, /api/tickets/stats, /api/tickets/:id. Reads Ticket, TicketMessage, TicketEvent. See Customer → Tickets.

4. Superadmins — /superadmin/superadmins

Manage superadmin users. Two surfaces:

• List (JWT) → GET /superadmin/superadmins (listSuperadmins, superadmin.controller.ts) — reads User (role superadmin).
• CRUD (secret-guarded) → superadmin-setup.routes.ts, mounted at /setup, guarded by verifyWebhookSecret (the SUPERADMIN_API_SECRET header, not a JWT):

Action	Method + Path	Handler	Collection
Create superadmin	POST /setup/superadmins	createSuperAdmin	User
List superadmins	GET /setup/superadmins	listSuperAdmins	User (read)
Update superadmin	PUT /setup/superadmins/:id	updateSuperAdmin	User
Delete superadmin	DELETE /setup/superadmins/:id	deleteSuperAdmin	User
Delete superadmin (JWT)	POST /superadmin/users/:userUID/delete	deleteSuperadmin	User

The secret-guarded setup router exists so the first superadmin can be bootstrapped before any superadmin JWT exists.

5. System Config — /superadmin/system-config

Global default presets, voices, fees, and version history that every org inherits. Two routers:

Superadmin defaults (superadmin.routes.ts):

Action	Method + Path	Handler	Collection
Get default config	GET /superadmin/system-config	getDefaultConfig	SystemConfig (read)
Update addon rates	PUT /superadmin/system-config/addon-rates	updateDefaultAddonRates	SystemConfig
Update platform fee	PUT /superadmin/system-config/platform-fee	updateDefaultPlatformFee	SystemConfig
Update P2P fee	PUT /superadmin/system-config/p2p-fee	updateDefaultP2pFee	SystemConfig
Locked-module display	PUT /superadmin/system-config/locked-module-display	updateDefaultLockedModuleDisplay	SystemConfig
Preset CRUD	POST/PUT/DELETE /superadmin/system-config/presets[/:presetId]	createDefaultPreset / updateDefaultPreset / deleteDefaultPreset	SystemConfig
Versions	GET /superadmin/system-config/versions	listDefaultVersions	ConfigVersion (read)
Rollback	POST /superadmin/system-config/versions/:versionNumber/rollback	rollbackDefaultVersion	SystemConfig, ConfigVersion
Voices	GET/POST/PUT/DELETE /superadmin/system-config/voices[/:voiceId]	listDefaultVoices / createDefaultVoice / updateVoice / deleteVoice	SystemConfig (voices)

Permission-gated config (systemConfig.routes.ts, mounted at /api/v2/config): preset/voice/version CRUD with requireSuperadminForConfigMutation + requireConfigEditPermission — e.g. GET /api/v2/config/status, POST /api/v2/config/fork, GET /api/v2/config/presets, GET /api/v2/config/versions/diff. See Dynamic Agent Config.

6. Provider Registry — /superadmin/provider-registry

The AI provider/model registry (STT/TTS/LLM capabilities per language). Route file: providerModelRegistry.routes.ts (mounted at /api/config/provider-registry, requireRole("superadmin")). Service: providerModelRegistry.service.ts.

Action	Method + Path	Collection
Language keys	GET /api/config/provider-registry/language-keys	— (static)
Create entry	POST /api/config/provider-registry	ProviderModelRegistry
List entries	GET /api/config/provider-registry	ProviderModelRegistry (read)
Get entry	GET /api/config/provider-registry/:id	— (read)
Update entry	PUT /api/config/provider-registry/:id	ProviderModelRegistry
Delete entry	DELETE /api/config/provider-registry/:id	ProviderModelRegistry

7. Number Management — /superadmin/providers

⚠️ Unverified — /superadmin/providers and /superadmin/org-provisioning both render NumberManagementPage.tsx; the menu links to /superadmin/providers.

Telephony provider registry + per-org provider enablement + rates. Route file: superadmin-provisioning.routes.ts (mounted at /superadmin/provisioning). Controller: superadmin-provisioning.controller.ts.

Action	Method + Path	Handler	Collection
Adapter catalog	GET /superadmin/provisioning/adapters	listAdapterCatalog	— (read)
Create provider	POST /superadmin/provisioning/providers	createProvider	Provider
List providers	GET /superadmin/provisioning/providers	listProviders	Provider (read)
Update provider	PUT /superadmin/provisioning/providers/:providerUID	updateProvider	Provider
Deactivate provider	POST /superadmin/provisioning/providers/:providerUID/deactivate	deactivateProvider	Provider
Set/get credentials	PUT/GET /superadmin/provisioning/providers/:providerUID/credentials	setProviderCredentials / getProviderCredentials	Provider (masked)
Credentials via login	PUT /superadmin/provisioning/providers/:providerUID/credentials/login	setProviderCredentialsViaLogin	Provider
List org providers	GET /superadmin/provisioning/orgs/:orgUID/providers	listOrgProviders	OrgProviderEnablement (read)
Enable/disable for org	POST /superadmin/provisioning/orgs/:orgUID/providers/:providerUID/{enable|disable}	enableProviderForOrg / disableProviderForOrg	OrgProviderEnablement
Set org rates	PUT /superadmin/provisioning/orgs/:orgUID/rates	setOrgRates	ProvisioningRate
Price breakdown	GET /superadmin/provisioning/orgs/:orgUID/providers/:providerUID/price-breakdown	getOrgProviderPriceBreakdown	— (read)
Refresh costs	POST /superadmin/provisioning/orgs/:orgUID/providers/:providerUID/refresh-costs	refreshOrgProviderCosts	Provider
Cross-org inventory	GET /superadmin/provisioning/inventory	getInventory	ProvisionedNumber (read)

See Phone Number Provisioning.

8. Credit Management — /superadmin/credits

Recharge any org and view platform-wide credit totals. Controller: credit.controller.ts.

Action	Method + Path	Handler	Collection
Recharge org	POST /superadmin/organizations/:orgId/recharge	rechargeOrganization	CreditTransaction
Platform transactions	GET /superadmin/credit-transactions	getPlatformTransactions	— (read)
Platform credit summary	GET /superadmin/credit-summary	getPlatformCreditSummary	— (read)

See Credit Management System.

9. Per-Org Rates — /superadmin/org-rates

Preferential per-org pricing overrides on top of the global defaults. Page: pages/superadmin/OrgRateManagementPage.tsx. Route file: orgConfigReplica.routes.ts (SA endpoints, mounted at /api/org-config). Controller: orgConfigReplica.controller.ts.

Action	Method + Path	Handler	Collection
Get org replica	GET /api/org-config/replica/:orgUID	getSuperadminOrgReplica	OrgConfigReplica (read)
Per-org addon rates	GET/PUT /api/org-config/replica/:orgUID/addon-rates	getSuperadminOrgAddonRates / setSuperadminOrgAddonRates	OrgConfigReplica
Per-org platform fee	GET/PUT /api/org-config/replica/:orgUID/platform-fee	getSuperadminPlatformFee / setSuperadminPlatformFee	OrgConfigReplica
Per-org P2P fee	GET/PUT /api/org-config/replica/:orgUID/p2p-fee	getSuperadminP2pFee / setSuperadminP2pFee	OrgConfigReplica
Per-org preset rate	PUT/DELETE /api/org-config/replica/:orgUID/presets/:presetId/superadmin-rate	setSuperadminOrgRate / removeSuperadminOrgRate	OrgConfigReplica
Per-second rate	PUT/DELETE /api/org-config/replica/:orgUID/presets/:presetId/superadmin-rate-per-sec	setSuperadminOrgRatePerSec / removeSuperadminOrgRatePerSec	OrgConfigReplica

Also note telephony per-org rates (setOrgRates → ProvisioningRate) under Number Management. See Call Fee Model.

10. OAuth Clients — /superadmin/oauth-clients

CRM OAuth client credentials. Route file: superadmin-oauth.routes.ts (mounted at /superadmin/oauth-clients). Controller: superadminOAuth.controller.ts.

Action	Method + Path	Handler	Collection
Create client	POST /superadmin/oauth-clients	createOAuthClient	CrmOAuthClient
List clients	GET /superadmin/oauth-clients	listOAuthClients	CrmOAuthClient (read)
Get client	GET /superadmin/oauth-clients/:id	getOAuthClient	— (read)
Update client	PUT /superadmin/oauth-clients/:id	updateOAuthClient	CrmOAuthClient
Delete (soft)	DELETE /superadmin/oauth-clients/:id	deleteOAuthClient	CrmOAuthClient
Regenerate secret	POST /superadmin/oauth-clients/:id/regenerate-secret	regenerateClientSecret	CrmOAuthClient

See Oktivo App Integration.

11. SIP Trunks — /superadmin/trunks

Create, sync, and manage SIP trunks. Route file: telephony.routes.ts (requireRole("superadmin")). Controller: telephony.controller.ts.

Action	Method + Path	Handler	Collection
Create trunk	POST /superadmin/sip-trunks	createTrunk	SIPTrunk
Create inbound trunk	POST /superadmin/sip-trunks/inbound	createInboundTrunkEndpoint	SIPTrunk
List trunks	GET /superadmin/sip-trunks	listTrunks	SIPTrunk (read)
Get trunk	GET /superadmin/sip-trunks/:trunkId	getTrunk	— (read)
Update trunk	PUT /superadmin/sip-trunks/:trunkId	updateTrunk	SIPTrunk
Delete trunk	DELETE /superadmin/sip-trunks/:trunkId	deleteTrunk	SIPTrunk
Remove number from trunk	POST /superadmin/sip-trunks/:trunkId/remove-number	removeNumberFromTrunk	PhoneNumber, SIPTrunk
Sync trunks	POST /superadmin/sip-trunks/sync	syncTrunks	SIPTrunk
List providers	GET /superadmin/providers (telephony)	listProviders	Provider (read)

External integration: LiveKit SIP + carriers. See SIP Trunk Overview.

12. Phone Numbers — /superadmin/phone-numbers

The platform number pool: add numbers, assign to orgs, change types. Route file: telephony.routes.ts. Controller: telephony.controller.ts.

Action	Method + Path	Handler	Collection
Add numbers	POST /superadmin/phone-numbers	addNumbers	PhoneNumber
Pool stats	GET /superadmin/phone-numbers/stats	getPoolStats	— (read)
List all numbers	GET /superadmin/phone-numbers	listAllNumbers	PhoneNumber (read)
Assign to org	POST /superadmin/phone-numbers/:id/assign-org	assignNumberToOrg	PhoneNumber
Unassign from org	POST /superadmin/phone-numbers/:id/unassign-org	unassignNumberFromOrg	PhoneNumber
Reassign trunk	POST /superadmin/phone-numbers/:id/reassign-trunk	reassignNumberTrunk	PhoneNumber
Delete number	DELETE /superadmin/phone-numbers/:id	deleteNumber	PhoneNumber
Update number type	PUT /superadmin/phone-numbers/:id/type	updateNumberType	PhoneNumber
Inbound stats	GET /superadmin/inbound/stats	getInboundStats	— (read)

See Phone Number Assignment.

13. Benchmarks — /superadmin/benchmarks

Model benchmark runs. Route file: benchmark.routes.ts (mounted at /superadmin/benchmarks and /benchmarks; requireFeature("benchmark"), superadmin bypasses). Controller: benchmark.controller.ts. Pages: pages/shared/BenchmarkListPage.tsx, BenchmarkCreatorPage.tsx, BenchmarkResultsPage.tsx.

Action	Method + Path	Handler	Collection
Create benchmark	POST /superadmin/benchmarks	create	Benchmark
List benchmarks	GET /superadmin/benchmarks	list	Benchmark (read)
Registry	GET /superadmin/benchmarks/registry	registry	— (read)
Validate model	POST /superadmin/benchmarks/validate-model	validateModel	—
Browse orgs/customers	GET /superadmin/benchmarks/browse/organizations[/:orgUID/customers]	listOrganizations / listCustomers	— (read)
Get / update	GET/PUT /superadmin/benchmarks/:id	getOne / update	Benchmark
Start / stop / judge	POST /superadmin/benchmarks/:id/{start|stop|judge}	start / stop / judge	BenchmarkRun
Delete	DELETE /superadmin/benchmarks/:id	remove	Benchmark

See Benchmark Pipeline.

14. Provider Capacity — /superadmin/provider-capacity

Concurrent-call capacity caps per provider. Route file: superadmin.routes.ts. Controller: providerCapacity.controller.ts.

Action	Method + Path	Handler	Collection
Capacity dashboard	GET /superadmin/provider-capacity/dashboard	getProviderDashboard	— (read)
Available providers	GET /superadmin/provider-capacity/available-providers	getAvailableProviders	— (read)
List capacity	GET /superadmin/provider-capacity	listProviderCapacity	ProviderCapacity (read)
Create capacity	POST /superadmin/provider-capacity	createProviderCapacity	ProviderCapacity
Update capacity	PUT /superadmin/provider-capacity/:id	updateProviderCapacity	ProviderCapacity
Delete capacity	DELETE /superadmin/provider-capacity/:id	deleteProviderCapacity	ProviderCapacity

See Concurrent Calling System.

15. Concurrency — /superadmin/concurrency

Platform concurrency allocation per org. Route file: concurrency.routes.ts (superadminConcurrencyRoutes, mounted under /superadmin/concurrency). Controller: concurrency.controller.ts.

Action	Method + Path	Handler
SA dashboard	GET /superadmin/concurrency/dashboard	getSuperadminDashboard
Presets capacity	GET /superadmin/concurrency/presets/capacity	getPresetsCapacity
Get org quota	GET /superadmin/concurrency/organizations/:orgUID/quota	getOrgQuota
Allocate org quota	POST /superadmin/concurrency/organizations/:orgUID/quota	allocateOrgQuota

Quota allocation is stored on the Organization / concurrency config. See Concurrency Management System.

16. Bug Reports — /superadmin/bug-reports

Cross-org bug reports submitted by any user. Reports are submitted via bug-report.routes.ts (POST /bug-reports); superadmins review them via superadmin.routes.ts. Controller: bug-report.controller.ts.

Action	Method + Path	Handler	Collection
List reports	GET /superadmin/bug-reports	listBugReports	BugReport (read)
Get report	GET /superadmin/bug-reports/:id	getBugReport	— (read)
Update status	PATCH /superadmin/bug-reports/:id/status	updateBugReportStatus	BugReport

See Bug Report System.

17. Account Settings — /superadmin/settings

The superadmin's own account. Page: pages/superadmin/AccountSettingsPage.tsx. Uses the shared auth/account endpoints (/auth/*).

Collections Written by This Dashboard

Primary collections: Organization, User, Role, SystemConfig, ConfigVersion, Provider, ProviderCapacity, ProviderModelRegistry, OrgProviderEnablement, CreditTransaction, ProvisioningRate, OrgConfigReplica, CrmOAuthClient, SIPTrunk, PhoneNumber, ProvisionedNumber, Benchmark, BenchmarkRun, BugReport. Full definitions in Data Collections.

How to Test (End-to-End)

1. Prerequisites: a superadmin account; backend + frontend running.
2. Organizations: create an org at /superadmin/organizations; confirm Organization + its admin User are created.
3. System Config: change a default preset rate, save, confirm SystemConfig + a new ConfigVersion entry, then roll back and confirm the previous value returns.
4. SIP Trunks: create a trunk, run sync, and confirm SIPTrunk reflects the live LiveKit state.
5. Phone Numbers: add a number, assign it to an org, confirm PhoneNumber.orgUID updates.
6. Superadmins: confirm POST /setup/superadmins fails without the SUPERADMIN_API_SECRET header and succeeds with it.

Troubleshooting

Symptom	Cause	Fix
/superadmin/* redirects to login	User is not role superadmin	Log in with a superadmin account
POST /setup/superadmins returns 401	Missing SUPERADMIN_API_SECRET header	Send the secret header; see superadmin-setup.routes.ts
SIP trunk shows stale state	Live carrier/LiveKit state drifted	Run POST /superadmin/sip-trunks/sync
Provider credentials show masked	By design — only last-4 are returned	Re-set credentials to change them
Org still on old pricing	Per-org override set in Per-Org Rates	Update/remove the /replica/:orgUID override
Benchmark blocked by feature gate	Role not resolved as superadmin	Verify the JWT role; superadmin bypasses requireFeature