View as tenant (operator impersonation)

The view-as-tenant feature lets a Vorel platform operator render the tenant-side dashboard (/inbox, /cases, /leads, /analytics, …) as that tenant, without needing a user account on the tenant. It is the support primitive for “what is the tenant’s admin actually seeing right now?”, load-bearing for incident response, data-sync debugging, and live verification of new features against real production data.

​

When to use it

​

When NOT to use it

• Routine admin work. Use the operator console at /admin/tenants/<id> for cross-tenant operator tasks: managing credentials, viewing audit logs, running cost rollups. View-as-tenant is for seeing the tenant-side UI, not for performing operator work.
• Bulk operations across tenants. If you’re doing something that touches multiple tenants, use the operator-side cross-tenant surfaces. Repeatedly starting and stopping view-as-tenant sessions for ten tenants is a code-smell; there is probably an operator-side bulk surface for what you’re trying to do.
• As a workaround for missing operator-side functionality. If you find yourself impersonating a tenant to do something the operator console should support, file an issue. The operator console is the surface that’s supposed to evolve to cover those gaps.

​

How to use it

​

Session semantics

• Cookie-scoped. The impersonation lives in an 8-hour session cookie. There is no server-side persistent state recording “operator X is currently impersonating tenant Y”; the cookie is the only carrier. Two browsers running side-by-side can each have independent impersonation contexts.
• 8-hour expiry. The cookie expires 8 hours after the session starts. After expiry, the dashboard reverts to your operator identity automatically; no impersonation_ended audit row fires for the silent expiry (the row only fires on explicit stop). Auditors who need to know when a session ended can infer it from the next impersonation_started row or from access patterns.
• Single-tenant at a time. You can impersonate one tenant at a time. Starting a new impersonation while another is active replaces the active one (an impersonation_ended row fires for the old, an impersonation_started row fires for the new).
• No write actions during impersonation are tagged as the tenant. Mutations you perform while impersonating still carry your operator identity in their audit rows, so a write that happens during an impersonated session is traceable back to the operator that performed it, not laundered through the tenant identity.

​

Audit-trail guarantees

Every start and explicit stop of an impersonation session writes an audit_log row:

• impersonation_started: fields: operator’s user id, target tenant id, reason text, IP address, user agent, ISO timestamp.
• impersonation_ended: fields: operator’s user id, target tenant id, ISO timestamp.

These rows are written into the tenant’s audit_log partition and are visible to the tenant’s admin at the tenant-side audit surface. The tenant admin can see that on 2026-05-19 at 14:32 UTC, Vorel operator Alice impersonated their tenant for the reason “debug data sync” and ended the session 17 minutes later. This is intentional: the tenant’s trust posture is that Vorel operators can impersonate, but every impersonation is visible to the tenant’s admin in the same surface they audit their own team’s activity. The audit_log table is append-only at the database level via a Postgres trigger; impersonation rows cannot be redacted or deleted by anyone (operator, tenant admin, or platform-level) except via the global retention regime. There is no admin path to hide an impersonation event from a tenant.

​

Security model

• Role-gated. Only users with platformRole === 'platform_operator' can start an impersonation. The gate runs in the server action that handles the form submission, independent of any client-side check.
• Defense in depth. The admin route group (/admin/*) is already operator-gated by middleware; the impersonation server action enforces the same role check independently. A bypass of the admin route would still fail at the action.
• Reason required. The reason field is required (3–200 characters); the action rejects an empty or too-short reason. Reasons are not validated for content; write “debug data sync” not “lol”. The audit row is what tenant admins read.
• No token persistence. There is no JWT, no API key, no server-side impersonation token table. The session cookie is signed with the same secret used for operator authentication. There is no way to “share” an impersonation session across browsers or recover one after the cookie is cleared.
• No bypass of tenant-side guardrails. Impersonation overlays the tenant identity onto your operator session; it does not grant you privileges that the tenant admin does not have. If a tenant’s admin cannot see archived conversations, neither can you while impersonating them.

​

Operating notes

• Two operators impersonating the same tenant is allowed. The audit log shows both. There is no “exclusive lock”; view-as-tenant is read-style support, not a destructive operation that needs serialization.
• Long-running session timeouts. An 8-hour cookie is long for a support session and short for a debugging session that spans a workday. If you need to span multiple workdays, re-start the impersonation each morning. Two impersonation_started rows on consecutive days for the same tenant is normal.
• Customer-facing notifications. Vorel does not email the tenant admin when an impersonation starts; the audit row is sufficient per the trust model. If a particularly sensitive tenant (PHI-adjacent, financial-services) wants per-event email alerts, that is a per-tenant configuration request via the operator console; the audit row remains the source of truth.

​

Related docs

• Security overview: multi-tenant isolation, append-only audit, role gates.
• Security, data handling: audit_log integrity, append-only triggers, right-to-erasure semantics.
• Compliance: DPA disclosure on operator-side access to tenant data.