Skip to content

Start impersonating a user

POST
/admin/users/{ref}/impersonate

Signs you in as another user so you can see what they see. The response sets a new session cookie for that user; your own session isn’t ended.

While impersonating you have the target’s capabilities, not your own. The session lasts at most 30 minutes; end it sooner with POST /auth/impersonation/end. Only requests that send the new cookie run as the target: a request with a valid API token in Authorization is still handled as the token’s user.

The checks run in this order: a 403 without auth.impersonate, a 400 if you’re already impersonating or name yourself, a 404 for an unknown user, and a 403 if the target holds system.admin globally. The target’s account status isn’t checked, and they aren’t notified.

Starting and ending are recorded in the audit log on a best-effort basis, as admin.impersonation.started (with your optional reason) and admin.impersonation.ended, each naming you as the actor and the target as the subject. Ordinary actions you take while impersonating are recorded with the target as the actor; the audit log doesn’t add your name to them.

ref
required
integer format: int64
object
reason

Why you’re impersonating, such as a ticket number. Recorded in the audit log. Optional.

string
<= 500 characters

Impersonation started. The response sets the new session cookie.

The impersonation that just started, with enough to show who you’re acting as without another request.

object
target_user_ref
required
integer format: int64
target_username
required
string
session_id
required

The new session’s id. It isn’t a credential: the session token is only in the cookie.

string format: uuid
expires_at
required

When the impersonation session expires, 30 minutes after it started. The cookie itself lasts until the browser closes, but stops working at this time.

string format: date-time

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed