Impersonation
Learn how to sign into your application as one of your users.
Impersonation allows administrators and support team members to assume the identity of any of your users, allowing them to reproduce or debug issues the user may be having in your application. The ability to see the application in an identical state as the user helps to greatly speed up the support process.
Since impersonation allows any member of your WorkOS team to bypass the normal authentication flow for a user, it is not enabled by default in any of your environments. You must have the Admin role in order to enable impersonation for an environment.
Navigate to Authentication → User Impersonation and select Configure to enable impersonation for your current environment.
To impersonate one of your users, navigate to Users, select the user you’d like to impersonate, and under Danger Zone select Impersonate User.
You will be prompted for the reason your are impersonating the user. It is optional to provide a reason in staging environments, and required in production. The reason will be recorded internally on the session.created event that is emitted whenever impersonation is used.
If the user is a member of more than one organization, you will also need to choose which of these organizations you will be signing-into as the user. You can read more about users and organizations in our dedicated guide.
Finally, click Impersonate user to start an impersonation session, redirecting your browser to your application’s callback endpoint with an authorization code for the impersonated user. You can read more about how to implement a callback endpoint in our Quick Start guide.
Impersonation sessions automatically expire after 60 minutes.
Be aware that impersonating a user usually generally gives the same level of access as that user, allowing the impersonator to see the user’s information. If your application contains sensitive user data, see the Integrating impersonation section about how to customize your application when using impersonation.
User sessions that were initiated via impersonation will be clearly marked as such when viewing their details in the WorkOS Dashboard. Additionally, WorkOS emits a session.created event which you can view under the events for the user, or listen for in your application via the events API.
The session.created event has an impersonator field that contains information about the impersonation session, like the email of your team member who performed the impersonation, along with their reason for doing so.
No additional code is required to start using impersonation once you have integrated with WorkOS. However, many developers may want to augment their application’s behavior when your team members are impersonating one of your users.
The response from the Authenticate with Code API will include an additional impersonator field when the resulting session was created via impersonation, containing the impersonator’s email and reason for using impersonation. Similarly, the access_token will include an act claim with the impersonator’s email. Your application can use either in order to trigger impersonation-specific behavior.
A common enhancement is to change the appearance of the application in order to make it obvious to the viewer they are currently impersonating one of your users, such as a “Staff Bar” displayed at the top of the viewport. You may also want to restrict access to sensitive views or redact certain fields in your application.
If using the authkit-nextjs library, impersonation can be easily added by using the provided helper component.
After completing the setup instructions in the quick start guide, add the Impersonation component to your app code.
The above will automatically render a visually distinct frame on your page with an option to hide it or stop the impersonation session.
