Start an admin-impersonation session for a target user

POST

/admin/users/{ref}/impersonate

• Local development behind nginx (port 8088 by default)

Issues a NEW session bound to the target user but attributed to the calling admin via sessions.impersonated_by_user_ref. Sets the session cookie on the response so the very next request runs under the target’s identity. The admin’s prior session is NOT revoked — ending impersonation issues a fresh admin session via /auth/impersonation/end.

Gated on auth.impersonate (admin-only by seed). Refusals (defense-in-depth):

• 400 — self-impersonation (admin impersonating themself).
• 400 — chain attempt (admin tries to impersonate while already impersonating).
• 403 — target holds system.admin (no privilege- escalation by chaining; admins must coordinate out-of-band to impersonate each other).
• 404 — target user not found.

Audit emits admin.impersonation.started with subject = target, actor = admin, metadata.session_id + reason.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Path Parameters

ref

required

integer format: int64

Request Body

object

reason

Admin-supplied justification (ticket number, brief context). Recorded in the impersonation.started audit event. Encouraged but not required.

string

<= 500 characters

Responses

200

Impersonation session minted + cookie set.

Returned by POST /admin/users/{ref}/impersonate when the impersonation session has been minted + the cookie set. The frontend uses this to render the persistent “you are acting as @target” banner without an immediate reload.

object

target_user_ref

required

integer format: int64

target_username

required

string

session_id

required

The newly-minted impersonation session’s id.

string format: uuid

expires_at

required

When the impersonation session hard-expires (default 30 min from start). The admin can end earlier via the “End impersonation” button.

string format: date-time

400

Malformed request

object

error

required

Human-readable error summary

string

Example

the request could not be completed

401

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"
}

403

Authenticated but missing required capabilities

object

error

required

Human-readable error summary

string

Example

the request could not be completed

404

Resource not found

object

error

required

Human-readable error summary

string

Example

the request could not be completed