Impersonate a user (admin and owner only)

Impersonation lets a workspace owner (or super_admin) act AS another user — to debug a permission issue, reproduce a bug they reported, or step in to assist. Initiate from People page → action menu → Impersonate. A red banner shows "Impersonating [name]" throughout the session. Click Exit to return to your own session. Every action during impersonation is audited with both your ID and the target's ID.

Who is this for

Owners, super_admins, and (in some configurations) admins helping a member debug an issue they can't reproduce themselves. Also useful for hands-on training: "Let me show you exactly what I'd do."

Two flavors of impersonation

Wevion has two impersonation endpoints with different scopes:

POST /api/v1/admin/stop-impersonate ends either kind of impersonation session.

If you're a workspace owner, you can only impersonate users inside your workspace. If you're a super_admin, you can impersonate across workspaces.

admin role does not grant impersonation by default — only owner+ and super_admin. This is intentional: impersonation is a sensitive operation with strong audit obligations.

Before you impersonate

• Get the user's verbal or written consent (it's their session you're stepping into). Wevion's audit log proves who impersonated whom, but pre-consent prevents misunderstandings

• Know what you want to verify or fix: don't impersonate "to look around" — the audit log will show every action

• Be prepared to exit cleanly: don't leave an impersonation session open while you walk away

How to impersonate

Step 1: Open People page

Navigate to Settings → Team → People. Find the target user.

Step 2: Click the action menu → Impersonate

The three-dot menu has Impersonate option (only visible if your role allows). Click it.

Step 3: Confirmation modal

A modal shows:

• Target user's name + email + role

• Warning: every action will be audited

• Suggested duration: keep impersonation sessions short (< 15 minutes recommended)

• Confirm button

Click Start impersonating. Backend sets the x-impersonate-user header on subsequent requests. Your request.adminUser field remembers your original identity.

Step 4: You're now in their session

The page reloads as the target user:

• Red banner at top: "Impersonating [name] — [Exit]"

• All UI permissions match the target's role (you can do less than you usually do, if they're a viewer)

• All data shown is what they would see (their workspaces, their permissions)

• Their preferences apply: theme, language, timezone display

Step 5: Do what you needed to do

Debug the issue, reproduce the bug, perform the fix on their behalf. Be intentional and brief.

Step 6: Exit

Click Exit in the red banner. Backend calls POST /api/v1/admin/stop-impersonate. The page reloads as YOU. The banner disappears.

If you forget to exit, the impersonation session times out after 30 minutes of inactivity for safety.

What is audited

Every API request during impersonation includes both IDs in the audit log:

{
  "action": "<whatever-the-action-was>",
  "user_id": "<target-user-id>",      // who appeared to do it
  "metadata": {
    "impersonated_by": "<your-user-id>",  // who actually did it
    "started_at": "...",
    "...": "..."
  }
}

So when reviewing the audit log later, you (and other admins) can clearly see actions taken during an impersonation session and by whom.

Who CANNOT be impersonated

• super_admin: no one can impersonate a super_admin (not even another super_admin)

• Users with active 2FA: depends on configuration; in some setups 2FA-protected users require their own active session to bypass impersonation

• Users in another organization (unless you're super_admin in their Org)

Stop-impersonate gotchas

• If your session expires while impersonating (long idle), you may be logged out entirely. Re-login lands you in your own session, not in the impersonation.

• If the target user changes their password / role / status during your impersonation, your impersonation may break mid-action. Re-try without impersonation if so.

• Impersonation does not allow you to change the target's own profile (their email, password, 2FA) — those endpoints require their authenticated session, not impersonation.

Cannot impersonate myself

You cannot impersonate your own user (no point + would break the audit trail). UI greys out the menu option on your own row.

What you'll see throughout

Common issues

• "Impersonate" not in menu: your role lacks permission. Need owner or super_admin.

• Cannot impersonate this user: target is super_admin, or in another org, or has block enabled.

• Banner missing during impersonation: rare UI bug. Refresh — banner should appear. If still missing, exit and re-impersonate.

• Actions during impersonation didn't take effect: check audit log; if the action was attempted but failed (e.g. role mismatch), the log shows the failure. Permission of target user applies, not yours.

• Stuck after Exit: page didn't reload cleanly. Refresh manually.

• Multiple impersonation sessions at once: not allowed. Starting a new impersonation while one is active automatically exits the previous.

Best practices

1. Always get consent before impersonating, except in clear emergencies

2. Keep sessions short: < 15 minutes

3. Document what you did in a follow-up message to the user

4. Don't impersonate to read sensitive data you wouldn't otherwise have access to (could violate privacy expectations even with audit)

5. Review audit log periodically for unusual impersonation patterns

6. Disable impersonation org-wide in Enterprise SSO if you want a stricter policy (talk to your CSM)

Related

• Security best practices for your team — when to allow/limit impersonation

• Read your audit log — verify impersonation activity

• Roles and permissions — full reference — who can impersonate