Stytch offers user impersonation functionality that allows you to log into your application as a specific end user
in order to troubleshoot and debug securely.
Note that the user impersonation functionality described here does not allow your customers’ administrators to impersonate Members of
their Organization. Rather, it allows members of your own company to impersonate end users.
Enabling user impersonation for your Stytch project
User impersonation is disabled by default for each of your Stytch projects. In order to enable it, a member of your team with the
Admin role in the Stytch Dashboard should navigate to the Password and User Policies page
and toggle on the Allow user impersonation setting. Be sure to click Save after modifying the setting.
Generating a user impersonation token
Once user impersonation has been enabled for your project, team members with the Admin, Developer, or Support Manager roles
can begin the user impersonation flow by selecting the Member they’d like to impersonate on the Members page,
scrolling down, and clicking Impersonate Member.
Your team member will be asked to provide a reason for impersonating the Member, which will be available later on for auditing purposes. They’ll then click
Launch in new tab, which initiates the user impersonation flow in a new browser tab at your project’s default login redirect URL
with an impersonation token appended to the query parameters. Here’s an example:
Note that it is not possible to generate a user impersonation token programmatically. If that is a requirement for your
use case, see the Programmatic user impersonation section below.
Authenticating a user impersonation token
Your application should then retrieve the impersonation token from your login redirect URL’s query parameters and authenticate it via the
Authenticate impersonation token endpoint.
If you’re using our frontend JavaScript SDK, you can authenticate the token via the authenticateByUrl method.
However, you’ll first need to enable the Authenticate member impersonation tokens setting on the Frontend SDK Configuration page in the Stytch Dashboard.
At this point, you’ll receive a new Member Session for the target user. Member Sessions created through user impersonation always have a duration of one hour, and can be explicitly revoked via the
Revoke Session endpoint. They contain a single factor in their authentication_factors array of type impersonated that includes the impersonator’s email address.
Here’s an example Member Session that was created through user impersonation:
Member Sessions created through user impersonation can be authenticated via the Authenticate session
endpoints or SDK methods using the session_token or session_jwt values from the Authenticate user impersonation token response.
Audit logging
After a user impersonation token is authenticated, you’ll find an event in the Stytch Dashboard’s Activity tab with
an action value of B2BAuthenticateMemberImpersonationToken. This event will contain additional details about the user impersonation,
such as the member_id, organization_id, the impersonator’s email address, and the reason that the impersonator provided for the
impersonation. If you take advantage of our Event log streaming feature,
the user impersonation logs are available there as well.
We also emit a webhook with an event type of direct.member.impersonate whenever
a Member is impersonated.
Programmatic user impersonation
For security purposes, we do not provide an API endpoint that generates user impersonation tokens. However, programmatic user
impersonation may be desirable for some use cases.
If you understand and accept the security implications, it is possible to use our Trusted Auth Tokens feature to programmatically
generate a Stytch Session on behalf of a Member. See our Custom auth factors
guide for implementation instructions.
If you choose to use Trusted Auth Tokens for user impersonation, you will be responsible for maintaining your own access controls, audit logs,
and other security guardrails.
If implemented improperly or without sufficient protections against misuse, user impersonation can introduce serious security
risks in your application.
