Skip to main content
Impersonation lets an admin send requests as if they were a specific non-admin user, so you can see exactly what that user sees. It’s the fastest way to reproduce a permission issue, validate a policy change, or debug a user-reported bug from inside their account.

​
Starting a session

You can start impersonation from two places, both gated by the impersonation.start capability:
  • The app-shell popover. A popover in the application shell lets you pick a user and start acting as them. Super admins get a tenant filter to reach users in any tenant they manage.
  • A member’s detail page. The Impersonate this user action on a member’s detail page starts a session targeting that user.
While a session is active, the shell shows who you’re acting as, and you end the session from the same popover.

​
Who can be impersonated

The backend applies four gates before allowing a session — the UI mirrors them, but the server is authoritative:
  1. You must be an admin (tenant_admin or super_admin).
  2. The target must be active. Deactivated users can’t be impersonated.
  3. The target must not be an admin. You can’t impersonate another tenant_admin or super_admin.
  4. Same tenant, unless you’re a super admin. A tenant_admin can only impersonate within their own tenant; a super_admin can cross tenants.

​
Session lifetime and revalidation

Impersonation sessions are time-boxed to one hour by default (configurable per deployment). Every request you make while impersonating is revalidated at request time against an active, non-expired session:
  • If the session is valid, the request runs as the target user.
  • If the session is expired, revoked, or missing, the act-as overlay is quietly dropped and the request continues as you (the acting admin) — it is not rejected with an error. In other words, an expired session fails safe back to your own identity rather than blocking you.

​
What impersonation does and doesn’t do

  • You see what they see. The tools they can call, the groups they’re in, the integrations they’ve linked — the same surface they get.
  • You don’t gain access. If the target can’t read BigQuery, neither can you while impersonating. Impersonation is not privilege escalation.
  • Admin targets and admin-only actions are out of reach. You can’t impersonate an admin, and the target’s own non-admin permissions bound what you can do.
Verify before relying: while a session is active the shell shows a hint that “Write actions are blocked while you are viewing as another user.” This suggests impersonation is a read-only view rather than one where writes execute as the target. Before telling users that actions you take while impersonating happen as them (sending mail, posting to Slack, writing to Salesforce), confirm against the current build whether writes are actually blocked or actually executed as the target — the UI copy and the enforcement should be checked together.

​
Common workflows

​
”User X can’t see the Salesforce CRM tool”

  1. Start impersonating user X.
  2. Open the surface that needs Salesforce.
  3. If the tool is missing, check X’s permission groups and their policies — add X to a group with the right access level, or update that group’s policy.
  4. End the session and confirm with X.
  1. Save the policy change.
  2. Impersonate a representative legal-team member.
  3. Try the workflows that group depends on, and adjust before users feel it.

​
Notes

  • End sessions when you’re done rather than relying on the one-hour expiry.
  • Impersonation is audited. Start, end, and denied events are emitted to the identity audit stream, capturing both the acting admin and the target. That stream has no dedicated UI — see Policy audit.