Super-Admin Panel
Super-Admin Panel — MC #104287
Shipped: 2026-06-27
Environment: rg-qody-demo (Azure Container Apps)
Revisions: qody-api--0000046 · qody-admin--0000026
Commits: 749108b (API) · 594d9c9 (Admin frontend)
Validation: Independent code verifier · Securion security
peer-review · Proveo live E2E · John live curl
Scope
Five capabilities were shipped and verified live. One capability (A-03, per-merchant Monri credential vault) is explicitly deferred and not yet built.
A-01 — Merchant Onboarding UI
Provides SUPERADMIN users with the ability to create new merchants and control their lifecycle from the admin panel.
-
Backend:
POST /superadmin/merchants— creates a new merchant/org record. -
Backend:
POST /superadmin/merchants/{id}/suspend— suspends a merchant; guest ordering blocked at venue level. -
Backend:
POST /superadmin/merchants/{id}/activate— re-activates a suspended merchant. -
Frontend:
MerchantsTab— create modal + per-row suspend/activate buttons in the super-admin panel. -
A suspended venue returns 404 on the
/superadmin/impersonate/{venueId}endpoint (see A-06).
A-02 — Per-Merchant Fee Management
Allows SUPERADMIN to configure per-venue commercial terms with enforced range guards at multiple layers.
-
Endpoint:
PUT /superadmin/merchants/{id}/fees -
Bug fixed: Frontend previously sent
PATCH(405 Not Allowed); corrected toPUT. -
Range guards (enforced at Kotlin level + DB CHECK constraint, migration
V10):
- Platform fee: 0.3% – 0.7%
- Monthly fee: 29 – 49 KM
- Out-of-range input: HTTP 400 with descriptive message.
- Valid input: HTTP 200.
- Proveo re-verified the 500→400 fix after the range-guard correction.
A-03 — Per-Merchant Monri Gateway Credential Vault (DEFERRED)
Not yet built. Deferred, externally blocked on:
- Monri test credentials pending (MC #104270).
- Azure Key Vault architecture decision pending.
Design intent: per-venue Monri credentials stored encrypted in Azure Key Vault; routing logic in payment service retrieves at request time. No implementation exists in the current revision.
A-04 — Cross-Merchant Transaction Search
Enables SUPERADMIN to search across all venues/merchants for specific transactions.
-
Endpoint:
GET /superadmin/transactions?search=<query> -
Server-side
ILIKEmatch onproviderPaymentIdandorderNumber. - Scope: all orgs/venues (superadmin only; RLS bypassed for this role).
A-06 — Controlled Support Impersonation
Allows SUPERADMIN to obtain a short-lived, venue-scoped session token to diagnose issues within a specific merchant's context.
-
Endpoint:
POST /superadmin/impersonate/{venueId} -
Returns a 30-minute MANAGER-scoped JWT (
type=impersonate). - Venue-scoping enforced at Postgres RLS level (not cosmetic application-layer filtering).
-
Every call writes a mandatory
audit_logrow (action=superadmin_impersonate). - Token issuance is atomic with the audit write: the transaction aborts and returns an error if the audit insert fails — no token without an audit trail.
- Returns 403 for non-SUPERADMIN callers; 404 for suspended venues.
Security Design — Impersonation
| Control | Implementation | Rationale |
|---|---|---|
| Least privilege role | MANAGER-scoped JWT (not OWNER, not SUPERADMIN) | Limits blast radius; cannot modify org settings or fees |
| Short TTL | 30-minute token expiry | Reduces window for token misuse or exfiltration |
| Mandatory audit | Atomic audit_log write; aborts on failure | No impersonation can occur without a traceable record |
| RLS venue isolation | Postgres Row-Level Security enforces venue boundary | Confirmed real by Securion peer-review (HIGH finding: audit-atomicity — fixed before ship) |
| SUPERADMIN gate | 403 for any other role | Endpoint unreachable to merchant users or kitchen/waiter roles |
Securion finding (HIGH — fixed): Initial implementation issued the token before writing the audit row. Fixed to wrap both operations in a single DB transaction; token is returned only after the commit succeeds.
A-08 — Monthly Billing Export
Provides SUPERADMIN with a per-venue revenue and fee CSV for a given calendar month.
-
Endpoint:
GET /superadmin/billing-export?month=YYYY-MM -
CSV columns:
venue_id,venue_name,org_id,org_name,currency,period_start,period_end,total_turnover,platform_fee_pct,fee_owed,monthly_fee,total_owed -
Frontend:
BillingTabwith a month picker; exports on demand.
Validation Summary
| Verifier | Method | Result |
|---|---|---|
| Independent code verifier | Static code review | PASS |
| Securion (Parisa Tabriz) | Security peer-review of A-06 impersonation | HIGH finding (audit atomicity) — fixed; venue-scoping confirmed RLS-real |
| Proveo (Angie Jones) | Live E2E: 4 PASS + A-02 range-guard 500→400 re-verify | PASS |
| John | Live curl against rg-qody-demo endpoints | PASS |
What Is NOT in This Release
- A-03 (Monri credential vault): Deferred — blocked on Monri test creds (MC #104270) and Key Vault architecture.
- Support password-reset UI, merchant onboarding billing, suspend/activate per-merchant billing — tracked separately in MC #104303.