User impersonation lets a trusted operator temporarily act as another user in the same Appwrite project, without sharing credentials. The operator signs in as themselves first, then sets a single impersonation target on the client. Appwrite resolves that target and executes requests using their permissions. This is especially useful when you need to: - Reproduce a bug that only appears for a specific user - Verify permissions and feature access from the user's point of view - Help customer support teams troubleshoot account issues - Review onboarding or upgrade flows exactly as an end user sees them ## How it works Impersonation follows four steps: 1. Enable the `impersonator` capability for a trusted operator. 2. Have that operator sign in normally using any supported Appwrite Auth flow. 3. Set exactly one impersonation target on the Appwrite client. 4. Appwrite resolves the target user and evaluates the request as that user. ##### User authentication is required Impersonation only works on requests that are already authenticated as a user with impersonation enabled. In server-side flows, an API key alone is not enough. You must also set a valid operator session on the client. When impersonation is active, the returned user model includes `impersonatorUserId`. Your app can use this to show a visible banner or disable risky actions while someone is acting on behalf of another user. ## Enable impersonation for an operator You can grant a user the impersonator capability in two ways: - In the Appwrite Console under **Auth > Users**, open the user's profile and toggle on the impersonator capability - Via the Users API, by setting the `impersonator` field to `true` on the user ```server-nodejs ``` Only grant this capability to internal users (support agents, QA engineers, or operations staff) who need to see the app exactly as a specific end user would. ##### Recommended setup Create a dedicated internal operator account for each team member instead of sharing one support account. This makes it easier to review internal audit activity and control access over time. When a user is marked as an impersonator, Appwrite also grants them the `users.read` scope. This allows trusted operators to list users in the project, which is especially useful when building internal admin-style tools that let support or QA teams search for a user and choose who to impersonate next. ## Initialize an impersonated client After the operator signs in, initialize the Appwrite client as usual and set exactly one impersonation target. Only one target can be active per request; using more than one is not supported. ##### SDK support Make sure you are using an Appwrite SDK version that supports impersonation. In client SDKs, the operator's session is persisted automatically after login, so enabling impersonation is just a matter of setting the right option on the client before making requests. ## By user ID Impersonating by user ID is the most precise option. Use it when your internal tools already store the Appwrite user ID or when an operator selected a user from your support dashboard. ```client-web ``` ## By email Impersonating by email is useful in admin panels and support workflows where operators search for users by email address first. ```client-web ``` ## By phone Impersonating by phone is helpful for support flows where the phone number is the primary identifier or when your app is centered around SMS-based authentication. ```client-web ``` ## Choosing the right identifier All three options result in the same impersonated session. The difference is which identifier your operator workflow has available: - Use **user ID** when you already have the canonical Appwrite ID - Use **email** when support teams search by email address - Use **phone** when your app is centered around phone login or phone-based onboarding Only set one impersonation value at a time. If you need to switch targets, create a fresh client or replace the previous impersonation value before continuing. ## Build safe support tooling Impersonation is most useful when you wrap it in explicit operator UX: - Use the automatically granted `users.read` scope to build a user picker or searchable support view - Show a clear banner while impersonation is active - Display both the operator identity and the effective user identity - Require an explicit action to start impersonation - Let operators stop impersonating with one click - Limit impersonation features to internal tools and trusted roles ## Security and visibility Keep impersonation limited to trusted operators and internal tools. Important behavior to know: - Impersonation must start from a real user session, not an API key by itself. - Users with impersonation enabled are automatically granted the `users.read` scope. - The target user's permissions are used for the impersonated request. - The user model includes `impersonator`, which indicates whether that user can impersonate others, and `impersonatorUserId`, which is present only during an active impersonation session and identifies the operator performing the impersonation. - Internal audit logs attribute the action to the original impersonator and include the impersonated target in internal audit payload data. If you build an internal admin panel, use `impersonatorUserId` to make the impersonated state obvious at all times. ## More resources - [Manage users with the Users API](/content/docs/products/auth/users/index.html) - [REST API impersonation docs](/content/docs/apis/rest#impersonation-headers/index.html) - [Users API reference](/content/docs/references/cloud/server-nodejs/users/index.html)