Impersonation Endpoints
The impersonation endpoints allow authorized administrators to assume the identity of other users for troubleshooting purposes. All impersonation actions are fully audited. Requires ADMIN role or users:impersonate authority. Served by ImpersonationController at /api/v1/impersonation.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/impersonation/start | Start impersonation session |
| POST | /api/v1/impersonation/:sessionId/end | End impersonation session |
| GET | /api/v1/impersonation/sessions/active | Get active sessions |
| GET | /api/v1/impersonation/sessions/:sessionId | Get session details |
| GET | /api/v1/impersonation/sessions/:sessionId/validate | Validate session |
| POST | /api/v1/impersonation/sessions/:sessionId/record-action | Record audit action |
| GET | /api/v1/impersonation/audit | Get audit history (paginated) |
| GET | /api/v1/impersonation/audit/range | Get audit by time range |
| POST | /api/v1/impersonation/sessions/:sessionId/force-end | Force-end session (Admin) |
| DELETE | /api/v1/impersonation/users/:userId/sessions | Revoke all user sessions |
| GET | /api/v1/impersonation/stats | Get impersonation statistics |
POST /api/v1/impersonation/start
Starts an impersonation session. Returns a token that can be used to act as the target user.
{
"targetUserId": 42,
"reason": "Investigating user-reported dashboard rendering issue",
"ticketReference": "SUPPORT-1234"
}The reason field must be between 10 and 1000 characters. The ticketReference is optional but recommended for compliance.
| Status | Description |
|---|---|
| 200 | Session started, impersonation token returned |
| 403 | Not authorized to impersonate |
| 404 | Target user not found |
| 409 | Cannot impersonate (protected role or same-tenant restriction) |
Audit Trail
Every impersonation session records:
- The admin who initiated the session
- The target user being impersonated
- Start and end timestamps
- IP address and user agent of the admin
- The stated reason and ticket reference
- All actions performed during the session (via
record-action)
Error Codes
| Code | Status | Description |
|---|---|---|
UNAUTHORIZED_IMPERSONATION | 403 | Caller lacks impersonation permissions |
INVALID_IMPERSONATION | 409 | Target has protected role or same-tenant restriction |
USER_NOT_FOUND | 404 | Target user does not exist |
SESSION_NOT_FOUND | 404 | Impersonation session not found |
MAX_SESSIONS_EXCEEDED | 429 | Too many concurrent impersonation sessions |