User impersonation

Impersonation (“sign in as user”) lets an operator open a real session as one of your end-users to reproduce a bug or debug a support ticket. It is built so that everything is allowed, and everything is attributed: the impersonator can do what the user can do, and every action lands in the audit log naming both the user and the operator behind the session.

Enabling impersonation

Impersonation is disabled by default on every environment. Enable it per environment in the dashboard under environment settings. While disabled, the impersonate endpoint refuses to mint tokens with a 403 impersonation_disabled.

Impersonation is available on every plan, including the free tier. What the plan governs is volume: production environments include 5 impersonations per billing period (free-tier projects are metered over a rolling 30 days), and exhausting the allowance returns 402. An add-on lifts the cap to unlimited. Sandbox environments are not metered — once the toggle is on, the feature is available.

How a session is established

1. An operator with access to the environment initiates impersonation from the dashboard and must provide a reason (e.g. a support-ticket reference). The reason is required: the request is rejected without one.
2. The server mints a one-time token (10-minute TTL, stored hashed) and returns an impersonate URL carrying it in the URL fragment, so the token never appears in server or proxy logs.
3. Redeeming the token creates a session capped at 1 hour. The token is single-use: a second redemption attempt fails.

Where an impersonated session lands

An impersonated session has to land on a page in your own application that mounts the Torii SDK — that is what reads the token out of the URL fragment and establishes the session. A marketing page, a docs site, or your API host will load normally and sign nobody in.

Torii does not guess this from your allowed origins. An origin allow-list answers “may this origin talk to us”, not “is your app served here”, so set it explicitly under Settings → User & authentication → Impersonation. The dashboard suggests the concrete origins already allowed for the environment, and you can append a path (https://app.example.com/dashboard). Picking a URL in the impersonate dialog offers to save it as the environment’s default, so subsequent impersonations are one click.

Two rules the server enforces:

• the URL’s origin must be one the environment allows (it is re-checked at impersonation time, so revoking an origin invalidates the landing);
• the URL must carry no #fragment — Torii appends the token as one. If your app is hash-routed, pass a per-request redirectUrl to the backend API below instead: that link redirects to your URL verbatim and appends nothing.

With no landing URL configured and none supplied in the request, the dashboard mint is refused (422 redirect_url_required) rather than sent somewhere arbitrary. A backend mint still returns its token, with url: null — see below.

Minting from your backend

You can also mint an impersonation token from your own backend with your secret key, instead of from the dashboard:

POST /api/server/v1/users/{userId}/impersonation-token
{ "actorUserId": "<the operator this act is on behalf of>",
  "reason": "Investigating support ticket #4821",
  "redirectUrl": "https://app.example.com/dashboard" }   // optional

The response carries the raw token, its expiresInSeconds, and a ready-to-use url:

• url is a navigable link on your environment’s Frontend API host. Hand it to an operator: opening it in a browser establishes the impersonated session and redirects to redirectUrl (or, if omitted, your environment’s configured impersonation landing URL, above). The token rides the query string, so the link is single-use and short-lived by design. It is null when neither is set, and also when the configured landing URL’s origin is no longer allowed (revoking an origin invalidates it) — redeem the token via POST in those cases.
• token is for programmatic redemption: POST it to /_torii/auth/session/impersonate to receive an access token in the response body (and the session cookie).

actorUserId and the target are both scoped to the secret key’s environment; reason is mandatory and audited exactly like the dashboard path. The same plan gate, per-period quota, and kill switch apply.

Attribution

Impersonated sessions are never anonymous:

• The access token carries an RFC 8693 act (actor) claim naming the impersonator, while sub stays the impersonated user, so your backend can always tell the two apart.
• Every audit event written during the session carries the impersonator’s identity in a dedicated field, alongside the acting user. “Show me everything operator X did while impersonating” is a single audit-log filter.
• Both the start (token creation) and the establishment (token redemption) of an impersonation are themselves audit events (user.impersonated), each carrying the operator’s reason, IP address, and user agent.
• The user’s session list in the dashboard clearly marks sessions that were established via impersonation.
• The audit log itself is tamper-evident: every entry is linked into a hash chain, and a scheduled integrity check raises a critical security alert if entries are modified or deleted: an operator cannot quietly erase the record of an impersonation.

What an impersonator can do

Everything the user can do. We deliberately do not ship a read-only mode or a blocked-action list: that is the standard way to treat impersonation. The accountability model is attribution, not restriction: a destructive action taken under impersonation is fully evidenced in the audit log, with the operator’s identity and stated reason attached.

If you want to restrict behavior in your own application during impersonated sessions, detect them via the act claim on the access token and branch accordingly.

Your obligations as data controller (GDPR)

When your staff impersonates one of your users, your organization acts as the data controller for that access; Torii processes it on your instruction. The platform gives you the technical safeguards: purpose limitation via the mandatory reason (Art. 5(1)(b)), accountability via the audit trail (Art. 5(2)), and security via one-time hashed tokens and short session caps (Art. 32). But two obligations stay on your side:

• Disclose support access in your privacy notice. Your users should be able to read that authorized staff may access their account for support and debugging purposes (Art. 12–14 transparency).
• Answer access requests from the audit log. If a user exercises their right of access (Art. 15), the audit log lets you report exactly who accessed their account, when, and why.

Torii’s data processing agreement will list impersonation as an instructed processing activity.