Mailmus
Auth

Sign in as a user

Open your app signed in as one of your users, to see exactly what they see, without their password and without leaving them exposed.

When a user writes in that something is wrong, the fastest way to understand it is to look at your app through their eyes. From the dashboard, a member of your team can open your app signed in as that user, reproduce the problem, and leave.

Available on the Pro and Scale plans.

Start a session

Open Customers, pick the user, and choose Sign in as this user in the Support card. Pick where your app should open: one of the return addresses allowed for this project. A new tab opens your app, signed in as that user.

Your app receives the session in the address, like any hosted sign-in. With the browser SDK (@mailmus/auth 0.6.0 or later), call auth.oauth.handleRedirectCallback() when that page loads, the same call as for OAuth in redirect mode. It accepts this session even though your app did not start it, because its token says a team member opened it.

Only people signed in to the dashboard with the Owner or Admin role can do this. An API key cannot: the history must always name a person.

What the session can and cannot do

The session lasts at most 60 minutes, and cannot be extended by refreshing it.

During that time, anything only the user should decide is refused, whatever your app sends:

  • adding, confirming or removing a second factor;
  • signing out one of their devices;

Starting this session does not change the user's last sign-in date, and does not count them as an active user on your bill.

Recognize it in your app

With @mailmus/auth-react 0.5.0 or later, there is nothing to do: while a team member is signed in as a user, a banner stays at the bottom of every page, naming both, with an End session button. Pass impersonationBanner={false} to <MailmusAuthProvider> to place <ImpersonationBanner /> yourself, or to build your own from useAuth().actor.

With the browser SDK, auth.session.getState().actor holds { id, email } during such a session, and null otherwise.

On your backend, the session's access token carries an act claim naming the team member acting for the user:

const { payload } = await jwtVerify(accessToken, JWKS);
if (payload.act) {
  // payload.act.sub   — the team member's id
  // payload.act.email — their email
}

If you verify sessions through the API instead, the response carries the same information in actor, or null for an ordinary session. See Verify sessions in your backend.

Use it to refuse, in your own backend, anything you consider the user's alone: changing a payment method, deleting data, sending messages in their name.

What stays on record

Each session started this way is recorded:

  • in your team's audit log, with the name of the person who started it;
  • in the user's activity history, as a team member signing in on their behalf rather than as a sign-in of their own;
  • in the user's list of sessions: the Customer API returns the team member's email in impersonatedBy, or null for a session the user opened;
  • as a customer.impersonated webhook event, if you want to inform your users or keep your own record.

If your app shows users their own devices, the session appears there with supportSession: true, without the team member's email.

Mailmus does not email the user. Whether and how to tell them is your decision, and the webhook is there to let you do it.

On this page