Patiodesk Super Admin Portal — User Manual

Portal version: 20260523-0001 · Last updated: 2026-05-24

Overview

The Super Admin Portal (pbx-admin) is Patiodesk's central control panel. It runs at http://patioweb09:5050 and is used exclusively by Patiodesk operators to manage the entire fleet of deployed PBX instances, handle billing, monitor uptime, and issue licenses.

Clients have their own limited view through the Client Self-Service Portal at /portal.

Logging In

1. Navigate to http://patioweb09:5050
2. Enter your admin username and password
3. If MFA is enabled on your account, enter the 6-digit TOTP code from your authenticator app
4. You are redirected to the Fleet Overview dashboard

Default admin credentials are set via ADMIN_PASSWORD in the .env file at portal startup.
Session stays active for the browser session. Closing the browser logs you out.

Navigation

The left sidebar groups all features:

Fleet Overview (Dashboard)

URL: /

The main dashboard. Everything here updates live via Server-Sent Events — no manual refresh needed.

KPI Cards (top row)

Fleet Health Chart

Doughnut chart — visual breakdown of Online / Stale / Offline clients at a glance.

Fleet Alerts

Lists clients that need attention. Click any alert to jump to that client's detail page.
- CRITICAL (red) — offline for over 1 hour, trunk down, or SLA breach
- WARNING (amber) — stale heartbeat (10 min–1 hr), high resource usage

Version Distribution

Shows which software versions are running across the fleet. Useful to know how many instances need an upgrade after a release.

License Health

Quick count of Active / Expiring / Expired / Revoked licenses.

Recent Activity

Last 8 audit events across all admin users.

Live Calls

Real-time active call channels pulled from Asterisk AMI. Refreshes every 30 seconds. Shows channel name, caller ID, duration, and application.

Clients

URL: /clients

List of all registered PBX clients. Each row shows: - Client ID, company name, region - Status badge: Online / Stale / Offline - Last heartbeat time - Active license indicator

Adding a Client

1. Click + Add Client (top right)
2. Fill in: Client ID (must be unique), Company name, Contact name, Contact email, Region, Tags, Notes
3. Click Create Client

The client's PBX appliance will auto-register on its first heartbeat if the Client ID matches.

Client Detail Page

URL: /clients/<client_id>

Tabs across the top:

Overview tab

• Status card — current status, last seen, IP address, hostname, machine ID
• Health metrics — CPU %, Memory %, Disk % from last heartbeat
• Trunk status — SIP trunk registration state (Registered / Unregistered)
• Extensions — registered / total count
• Active calls — current call count
• Analytics (24h) — sparkline charts for CPU, Memory, and Active Calls over the past 24 hours
• 24h Uptime estimate and total alerts

Heartbeats tab

Raw table of all heartbeat records — timestamp, CPU, memory, disk, active calls, extensions, trunk state.

Alerts tab

All alerts ever generated for this client, newest first.

Edit panel (right column)

• Edit company name, contact details, region, tags, notes
• Click Save Changes to update

Editing a Client

On the client detail page, update any field in the right panel and click Save Changes.

Deleting a Client

On the client list, use the action menu → Delete. This removes the client and all heartbeat history. Irreversible.

Provisions

URL: /provisions

Provision records track when and how a PBX appliance was deployed for a client.

Creating a Provision Record

1. Click New Provision
2. Select the client
3. Fill in server details (IP, hostname, notes)
4. Set the provision date
5. Save

Provision records are informational — they don't trigger any automated deployment yet. They serve as an internal record of where each client's PBX lives.

Releases

URL: /releases

Track software versions across the fleet.

Creating a Release

1. Click New Release
2. Enter the version number (e.g. 2.1.0)
3. Add release notes
4. Mark as stable or beta
5. Save

Releases appear in the Version Distribution panel on the dashboard.

SLA Monitoring

URL: /sla

Daily uptime tracking per client. The system calculates SLA compliance automatically each day at 00:05 UTC.

How SLA is Calculated

• Expected heartbeats per day: 288 (one every 5 minutes)
• Actual heartbeats received are counted
• Uptime % = (actual / expected) × 100
• A day is marked breached if uptime % falls below the client's SLA target (default: 99.5%)

Fleet SLA Table

Shows each client's: - 30-day average uptime % - SLA target - Number of breaches in the last 30 days - Trend indicator

Per-Client SLA Detail

URL: /sla/<client_id>

30-day daily breakdown table — each row is one day showing: - Heartbeat count (actual vs expected) - Uptime % - Pass / Breach status

Use this page when a client disputes their SLA or when generating a monthly uptime report.

Licenses

URL: /licenses

Manage license keys issued to clients. Each PBX appliance checks its license on startup.

Issuing a License

1. Click Generate License
2. Select the client
3. Choose the plan (determines feature set and limits)
4. Set expiry date
5. Click Generate

A license key is shown once — copy it immediately. The key is delivered to the client to activate their PBX appliance.

License States

Revoking a License

On the license detail page, click Revoke. Use this if a client cancels or is suspended.

Billing

URL: /billing

Subscriptions

Each client has a subscription record linking them to a plan.

To create a subscription: 1. Go to Billing → click New Subscription 2. Select client and plan 3. Set billing cycle (monthly / annual) 4. Set start date 5. Save

Invoices

Invoices are created manually or auto-generated (if scheduler is configured).

To create an invoice: 1. Click New Invoice 2. Select the subscription 3. Set amount, period, due date 4. Save

Invoice states: Draft → Sent → Paid → Overdue

To mark as paid: Open the invoice → click Mark Paid.

API Keys

URL: /api-keys

API keys allow external systems (scripts, monitoring tools, Prometheus) to call the portal's API.

Creating an API Key

1. Click + New Key
2. Give it a name (e.g. "Prometheus scraper")
3. Select scope:
4. read — read-only access to metrics and fleet data
5. heartbeat — allows sending heartbeats
6. admin — full access
7. Click Generate

Copy the key immediately — it is shown only once.

Using an API Key

Pass it in the request header:

X-Api-Key: pd_live_xxxxxxxxxxxxxxxxxxxx

Prometheus Metrics

With a read-scoped key, scrape metrics at:

GET /api/v1/metrics
X-Api-Key: <your-key>

SIP Templates

URL: /sip-templates

Pre-built SIP provider configurations. When provisioning a new client, apply a template to auto-fill their PBX trunk settings.

Built-in Templates (6)

Creating a Custom Template

1. Click + New Template
2. Enter provider name, host/IP, port, transport (UDP/TCP/TLS)
3. Add authentication if required (username, password)
4. Set codec preferences
5. Save

Templates are reusable — one template can be applied to multiple clients.

Webhooks

URL: /webhooks

Send real-time event notifications to external URLs when something happens in the portal.

Creating a Webhook

1. Click + New Webhook
2. Enter the destination URL
3. Select events to subscribe to:
4. client.offline — client goes offline
5. client.online — client comes back online
6. sla.breach — SLA breach detected
7. license.expired — license expiry
8. heartbeat.received — every heartbeat (high volume — use carefully)
9. Add a secret (used to verify the payload signature on your end)
10. Save

Webhook Payload Format

{
  "event": "client.offline",
  "client_id": "acme-corp",
  "timestamp": "2026-05-24T14:30:00Z",
  "data": { ... }
}

Viewing Delivery History

Each webhook has a delivery log — click any webhook → Delivery Log to see past deliveries, response codes, and retry attempts.

Audit Log

URL: /audit

Every action taken by any admin user is logged here. Useful for: - Security reviews - Troubleshooting ("who deleted that client?") - Compliance

Each entry shows: timestamp, actor (user), action, resource type, resource ID, IP address.

Filters: filter by actor, action type, or date range.

Users

URL: /users

Manage admin portal users.

Adding a User

1. Click + New User
2. Enter username, email, password
3. Assign role: Super Admin or Viewer
4. Save

Changing a Password

Open the user → click Change Password → enter new password → save.

Disabling a User

Open the user → toggle Active off → save. The user cannot log in but their audit history is preserved.

My MFA

URL: /mfa/setup

Set up or reset TOTP-based two-factor authentication for your own account.

Enabling MFA

1. Go to My MFA
2. Scan the QR code with Google Authenticator, Authy, or any TOTP app
3. Enter the 6-digit code to confirm
4. Save backup codes somewhere safe

Disabling MFA

Open My MFA → click Disable MFA → confirm with your password.

Once enabled, every login requires the TOTP code after the password.

Settings

URL: /settings

System-level configuration for the portal.

Client Self-Service Portal

URL: /portal/login

A separate login for clients — they see only their own data.

Client Login

Clients log in with their Client ID and the portal password set by the admin.

Setting a Client's Portal Password

On the client detail page → Portal Access section → enter a password → save.

What Clients Can See

• Their own fleet status (online/offline)
• Their own SLA history (30-day)
• Their own invoices
• Their own heartbeat metrics

Clients cannot see other clients or any admin settings.

Heartbeat API

The deployed PBX appliances call this API automatically every 5 minutes. You do not need to call it manually. For reference:

POST /api/heartbeat/<client_id>
X-Heartbeat-Token: <shared-token>

{
  "cpu_percent": 23.4,
  "memory_percent": 61.2,
  "disk_percent": 44.0,
  "active_calls": 3,
  "extensions_registered": 8,
  "extensions_total": 10,
  "trunk_state": "Registered",
  "sip_errors_count": 0,
  "uptime_seconds": 864000
}

The token is set in .env as ADMIN_HEARTBEAT_TOKEN.

Starting and Stopping the Portal

Start

cd /home/patio-admin/pbx-admin
bash start.sh

Stop

pkill -f "gunicorn.*wsgi:application"

Check if running

curl -s -o /dev/null -w "%{http_code}" http://localhost:5050/
# 302 = running (redirecting to login)

Logs

tail -f /home/patio-admin/pbx-admin/error.log
tail -f /home/patio-admin/pbx-admin/access.log

Environment Variables (.env)

Troubleshooting