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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Request Body
Section titled “Request Body ”object
Why you’re impersonating, such as a ticket number. Recorded in the audit log. Optional.
Responses
Section titled “ Responses ”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
The new session’s id. It isn’t a credential: the session token is only in the cookie.
When the impersonation session expires, 30 minutes after it started. The cookie itself lasts until the browser closes, but stops working at this time.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completed