Skip to content
NovaVMS Manual

How scoped impersonation works

Support engineers need to see what the customer sees — the same dashboard, the same events, the same broken camera tile. A persistent “sees-all-orgs” JWT claim solves that problem and creates three worse ones: a single missed permission check in any handler exposes every tenant, SOC-2 CC6.1 auditors reject it on sight, and the customer Owner cannot tell when Novalien staff were inside their org.

Per D80, platform admins never hold standing access to a customer org. They mint a 30-minute scoped token per incident. Every action is audited. The token is revocable by the customer’s Owner. The design mirrors Eagle Eye Networks’ /authorizationTokens reseller pattern, which is the industry precedent for cross-org access in cloud VMS products.

The token lifecycle

  1. Request. Platform admin signs into /platform/login with their platform credentials. Platform JWT carries {platform_user_id, scope: "platform"} and no org_id. It cannot read any /api/v1/... endpoint on its own.
  2. Mint. Platform admin calls POST /api/v1/platform/orgs/{org_id}/impersonate with a required reason string (minimum 10 characters, example: "Zendesk #4412 — owner locked out after password reset") and an optional ticket_ref. See Cross-org search for finding the right org_id.
  3. Guardrails checked. Server verifies the target org has allow_platform_impersonation = true (D80, US-PLAT-12). If the Owner has opted out, the mint fails with 403 IMPERSONATION_BLOCKED. Server also enforces a max of 5 concurrent impersonations per platform admin.
  4. Token issued. Server returns a scoped JWT with {org_id: <target>, role: "admin", impersonation_id: <token_id>, expires_in: 1800}. The role is always admin, never owner — owner-only powers (billing, transfer-ownership, delete-org) require a real human Owner (D80, US-PLAT-13).
  5. Use. Every request made under this token writes a dual audit entry (see Audit expectations). The frontend renders a red “Impersonating {org} — ends in mm:ss” banner with an End impersonation button.
  6. Expire or revoke. After 30 minutes the token expires. It cannot be refreshed — re-impersonation requires a fresh POST /impersonate with a fresh reason. Logout, explicit POST /end-impersonation, or the customer Owner toggling off support access all revoke it immediately.

In emergencies (Owner unreachable, org locked out, security incident) the Novalien on-call lead can grant a break-glass mint. This is a process, not a product feature — it is logged as platform.impersonation_started with reason: "BREAKGLASS — <incident ID>" and reviewed in the next-day incident postmortem. See Incident response runbook.

What gets audited

Every action inside the customer org during impersonation writes to both logs simultaneously:

  • The customer’s org audit log (90-day retention) with actor_type = 'platform_admin_impersonating' and the impersonation_id. The Owner and admins see every platform action with a Platform Support badge in /admin/audit-log.
  • The platform audit log (365-day retention) with full platform-user identity, reason, and ticket_ref.

Neither log can be deleted by anyone, including the platform admin who created the entries. See Audit expectations for the full table.

Trade-offs

  • Inconvenience for support. Every investigation starts with a fresh mint and a written reason. There is no persistent “support session” shortcut. This is friction by design — it converts cross-tenant access into an explicit, per-incident event.
  • Trust for customers. In exchange, the Owner gets a real-time audit trail and a hard off-switch. Enterprise customers have declined competitor products for lacking this guarantee.
  • Break-glass is a process, not a bypass. There is no flag that disables the reason requirement or the dual audit. An unreachable Owner becomes a Novalien-internal escalation (senior staff, not a product feature), not a shortcut in the product.

See also