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 in production environments is plan-gated (Business and up); sandbox environments always have the feature available once the toggle is on.

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.

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 first configured application origin). The token rides the query string, so the link is single-use and short-lived by design. It is null when no landing could be resolved (no redirectUrl and no concrete application origin configured, e.g. a fresh sandbox) — redeem the token via POST in that case.
• 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.