Impersonate user

POST https://app.speybooks.com/api/v1/admin/users/{id}/impersonate

Create a short-lived impersonation session as the target user. Generates a JWT valid for 10 minutes with an impersonatedBy claim identifying the admin.

Flow

  1. Validate target user exists and has an organisation
  2. Generate JWT with 10-minute expiry and impersonatedBy: adminId claim
  3. Hash the token (SHA-256) and store in admin_impersonation_sessions with reason, admin ID, target user/org, and expiry
  4. Write USER_IMPERSONATED audit log entry
  5. Return the token and expiry

Request Body

  • reason — minimum 5 characters, required for audit trail

Security

  • Tokens are short-lived (10 minutes)
  • Only the SHA-256 hash is stored, not the raw token
  • All impersonation sessions are audited with IP and user agent
  • The impersonation claim is visible in the JWT payload

Returns 404 if the target user does not exist.

Path parameters

id string required
User ID to impersonate.

Response

200 Impersonation token (10-minute TTL) with target user details.
Show response fields
expiresAt string date-time
targetUser object
Show child attributes
email string
id integer
token string

Error codes

400 Invalid user ID or cannot impersonate admin users.
404 User not found.