Skip to content
Zautha

Impersonation

Impersonation lets your support team sign in as a user to see what they see. It is a Pro feature (plan_limit_reached otherwise), and every impersonation is recorded in the audit log.

Start one

Section titled “Start one”
  • From the dashboard: Impersonate on a user’s page signs you in to the application as the user, in a new tab, for 30 minutes. On a development instance the session opens on the hosted login, and the application gets it after one more sign-in there.
  • From your server: create an actor token with the Backend API (POST /v1/backend/actor_tokens), naming the user, the agent (actor.sub, your own id for them) and where to land (redirect_url). Open the token’s url in the agent’s browser. It works once, within 10 minutes by default (expires_in_seconds, 60 to 3,600), and the session it opens lasts 30 minutes by default (session_max_duration_in_seconds, 60 to 7,200). An unused token can be revoked.

The link opens the hosted login’s /impersonate page, which signs the browser in as the user; a session of that application already open in that browser is signed out. A banned user cannot be impersonated; on an instance that requires an organization membership, neither can a user without one (impersonation_unavailable).

In the session

Section titled “In the session”
  • The session token carries act: { sub, iss? }, where sub is the id your server gave (or the dashboard member’s user_…) and iss the dashboard’s origin for one started there. Every SDK exposes it as the session’s actor, and the Backend API’s session objects have actor too.
  • With the prebuilt components, every page shows a band: “You are signed in as … (impersonation).” with End session. It cannot be turned off. Without the components, show your own notice from actor.
  • The session may read, get tokens, switch organizations, sign out and start a new sign-in. Every other write (the profile, email addresses, password, two-step verification, passkeys, connected accounts, organizations, OAuth consent) is refused with impersonation_forbidden.
  • It never passes a reverification check (its fva is [-1, -1]), and an OIDC request with prompt=login or max_age cannot be satisfied in it.

Your own backend decides what an impersonating agent may do there: check actor before a sensitive action.