User impersonation

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.

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

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.

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.

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.

By email

Impersonating by email is useful in admin panels and support workflows where operators search for users by email address first.

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.

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
• REST API impersonation docs
• Users API reference