Admin Panel Guide
All /admin/* routes in the portal are restricted to users with globalRole = 'admin_msp'. Additional routes require specific MSP sub-role permissions. This guide walks through every admin section.
Access requirement
You must be logged in with a user whose user.role = 'admin_msp' in the database. Client admins (client_admin) do not see the admin section of the sidebar.
Navigation structure
The admin section appears below a separator in the portal sidebar. Items are filtered both by the top-level admin_msp role and optionally by a permission key (MSP sub-role permission):
| Route | Label | Icon | Required permission |
|---|---|---|---|
/admin/dashboard | Admin dashboard | BarChart3 | none (admin_msp) |
/admin/tenants | Tenants | Building2 | tenants.read |
/admin/leads | Leads | UserPlus | leads.read |
/admin/tenant-requests | Tenant requests | FileText | tenant_requests.read |
/admin/impersonations | Impersonations | Eye | impersonation.read_log |
/admin/team | MSP team | ShieldCheck | team.read |
/admin/settings/roles | Roles | KeyRound | roles.read |
/admin/discount-codes | Discount codes | Tag | none |
/admin/billing/fees | Billing fees | DollarSign | none |
/admin/onboarding-queue | Onboarding queue | ListChecks | none |
/admin/commissions | Commissions | BadgeDollarSign | commissions.manage |
/admin/my-commissions | My commissions | CircleDollarSign | none |
Admin dashboard (/admin/dashboard)
[Screenshot: /admin/dashboard overview cards]
Shows global metrics:
- Total tenants — count of all tenants by status (active, past_due, suspended)
- Monthly revenue — sum of
total_chargefrom openbilling_periods - Total calls this month — sum of
total_callsfrom open billing periods
Data source: trpc.admin.globalOverview → admin.service.getGlobalOverview().
Note: The revenue and calls figures come from billing_periods which has RLS. In the current implementation, these may show 0 if app.current_tenant isn't set for cross-tenant queries. A SECURITY DEFINER function is planned to fix this.
Tenants (/admin/tenants)
[Screenshot: /admin/tenants list view with status badges]
Lists all tenants with: name, slug, plan, status, phone count, line count, Stripe status.
Filters available: status (active, past_due, suspended, cancelled), text search (name or slug).
Actions from the list:
- Click a tenant name → goes to
/admin/tenants/:iddetail page - Create new tenant:
/admin/tenants/new
Tenant detail tabs (/admin/tenants/:id/*)
| Tab route | What it shows |
|---|---|
/overview | Contact info, plan, status badge, accountCode, extension range, Stripe IDs |
/edit | Edit form: name, slug, plan, extension range, account code, contact fields, internal notes |
/billing | Billing periods and invoices for this tenant. Links to invoice detail with InvoiceBreakdown. |
/users | Members of this tenant org. Options to deactivate/reactivate. |
/inventory | Phone numbers and trunk lines assigned to this tenant (Fase 11 tables — read-only for now) |
/config | tenant_billing_config: billing address, jurisdiction code, carrier mode override, tax exempt status, excluded fee codes |
/activity | tenant_activity_log entries — tracks status changes, plan changes, etc. |
Changing tenant status (from overview or edit tab):
active→suspended: blocks all non-billing portal access for the tenantsuspended→active: restores full access- Status changes should also be synced with Stripe subscription status (see Runbooks)
Leads (/admin/leads)
[Screenshot: /admin/leads list with source and status columns]
Lead capture from the landing page (POST /api/v1/leads). Leads are potential customers who expressed interest.
Columns: name, email, phone, company, message, source, status, created at.
Actions:
- Mark as
contacted,qualified,disqualified - Leads marked as
qualifiedcan be converted to tenants (create org + tenant from lead data)
Data source: trpc.admin.leads and trpc.leads.*.
Tenant requests (/admin/tenant-requests)
[Screenshot: /admin/tenant-requests queue]
Requests submitted by existing client_admin users from the portal Settings → "Request tenant" flow. These are expansion requests (e.g., a client wanting to add a second location).
| Status | Meaning |
|---|---|
pending | Newly submitted, needs review |
approved | Provisioned — new tenant created |
rejected | Denied with reason |
Navigate to /admin/tenant-requests/:id to review details and approve or reject.
Impersonations (/admin/impersonations)
[Screenshot: /admin/impersonations log table]
Read-only log of all impersonation sessions. Every entry shows: impersonator email, impersonated user email, organization, start time, end time, IP address.
Important: While impersonating a user, all write mutations (protectedProcedure mutations wrapped by impersonationAwareProcedure) are blocked. The impersonation session is read-only by design.
To start an impersonation session (from the tenant users tab): click "Impersonate" next to a user → opens a new session as that user → portal shows an impersonation banner → click "Exit impersonation" to return.
Data source: trpc.admin.impersonation.* and admin_impersonations table.
MSP team (/admin/team)
[Screenshot: /admin/team list of MSP users]
Lists all users with role = 'admin_msp'. Shows each user's MSP sub-roles.
Actions:
- Invite new team member (sends an MSP invitation email via
msp_invitationstable) - Assign/remove MSP sub-roles:
super_admin,billing_clerk,sales_rep,technician - Deactivate team member
Data source: trpc.admin.team.*.
Roles (/admin/settings/roles)
[Screenshot: /admin/settings/roles role-permission matrix]
Manage MSP role definitions and their permission assignments. The permission matrix shows which permissions each MSP sub-role has.
System roles (is_system = true) cannot be deleted. Custom roles can be created and assigned any subset of permissions.
Permission categories include: tenants, leads, billing, commissions, team, roles, impersonation, tenant_requests.
Data source: trpc.admin.roles.* → msp_role_definitions, msp_permissions, msp_role_permissions tables.
Discount codes (/admin/discount-codes)
[Screenshot: /admin/discount-codes list]
Promotional discount codes for new subscriptions. Shows code, discount type (percentage or fixed amount), applicable plans, expiry date, and usage count.
Data source: trpc.discounts.* → discounts table.
Billing fees (/admin/billing/fees)
[Screenshot: /admin/billing/fees fee catalog list]
The fee management interface. Shows all fee definitions with their status, type, rate, and jurisdiction.
Sub-routes:
/admin/billing/fees— fee list with filters (jurisdiction, category, status)/admin/billing/fees/new— create a new fee/admin/billing/fees/:id— fee detail: edit, history, impact analysis, test calculation/admin/billing/carrier-mode— view current carrier mode + requirements checklist/admin/billing/compliance— compliance dashboard: registration tracking by authority, totals
For full fee management documentation see Admin fees.
Onboarding queue (/admin/onboarding-queue)
[Screenshot: /admin/onboarding-queue]
Tracks tenant onboarding checklists. New tenants go through an onboarding flow managed by admin-onboarding.router.ts. Admins can see which steps each new tenant has completed.
Data source: trpc.admin.onboarding.*.
Commissions (/admin/commissions)
[Screenshot: /admin/commissions overview]
Full commissions admin panel. Requires commissions.manage permission. Sub-routes match the commissions sidebar:
| Route | Content |
|---|---|
/admin/commissions | Overview: active reps, pending statements, last payout |
/admin/commissions/vendedores | Sales rep list — create, invite, deactivate |
/admin/commissions/asignaciones | Tenant-to-rep assignments |
/admin/commissions/atribucion | Attribution log — which rep gets credit for which tenant |
/admin/commissions/ingresos | Revenue events list |
/admin/commissions/statements | Commission statements — generate, approve, mark paid |
/admin/commissions/configuracion | Commission settings: rates, payout schedule, MLM rules |
For commissions documentation see the Commissions section.
My commissions (/admin/my-commissions)
Available to all admin_msp users without additional permissions. Shows the current user's commission rep profile (if linked). If the user isn't linked to a commission rep, the page shows instructions on how to get set up.
Quick actions reference
| Task | Where to do it |
|---|---|
| Check tenant billing status | /admin/tenants/:id/billing |
| View invoice breakdown | /admin/tenants/:id/billing → click invoice |
| Suspend a tenant manually | /admin/tenants/:id/overview → change status |
| Invite a new MSP team member | /admin/team → Invite |
| Add a fee | /admin/billing/fees/new |
| Check compliance registration | /admin/billing/compliance |
| Generate quarterly tax report | trpc.adminFees.quarterlyReport (API, no UI yet) |
| Impersonate a client user | /admin/tenants/:id/users → Impersonate |
| Review impersonation log | /admin/impersonations |
| Approve/reject tenant request | /admin/tenant-requests/:id |