Starting Impersonation Sessions
Impersonation sessions are initiated by administrators through the POST /api/v1/impersonation/start endpoint. The system validates permissions, checks constraints, creates an audit record, and generates a scoped token.
Request Parameters
| Field | Type | Required | Constraints |
|---|---|---|---|
targetUserId | Long | Yes | Must be a valid user ID |
reason | String | Yes | 10-1000 characters |
ticketReference | String | No | Max 100 characters (e.g., SUPPORT-1234) |
{
"targetUserId": 42,
"reason": "User reports inability to access BI dashboard after recent permission changes",
"ticketReference": "SUPPORT-5678"
}Validation Checks
The service performs the following checks before starting a session:
| Check | Failure Behavior |
|---|---|
Caller has users:impersonate or ADMIN role | Returns 403 UNAUTHORIZED_IMPERSONATION |
| Target user exists | Returns 404 USER_NOT_FOUND |
Target does not have PLATFORM_ADMIN role | Returns 409 INVALID_IMPERSONATION |
| Maximum concurrent sessions not exceeded | Returns 429 MAX_SESSIONS_EXCEEDED |
| Caller is not impersonating themselves | Returns 409 INVALID_IMPERSONATION |
Response
On success, the endpoint returns an ImpersonationResult:
{
"sessionId": "imp-session-uuid",
"impersonationToken": "eyJhbGciOiJIUzI1NiJ9...",
"targetUser": {
"id": 42,
"email": "target@example.com",
"displayName": "Target User"
},
"expiresAt": "2026-02-12T16:00:00Z",
"maxDurationMinutes": 60
}The impersonationToken should be used in the Authorization: Bearer header for subsequent API calls. This token includes metadata marking it as an impersonation token.
Context Headers
During an impersonation session, all API requests made with the impersonation token automatically include:
| Header | Value |
|---|---|
X-Impersonation-Session | The session ID |
X-Impersonated-By | The admin's user ID |
X-Original-User | The target user's ID |
These headers are injected by the authentication middleware and cannot be forged by the client.
Active Sessions
To view currently active impersonation sessions, use GET /api/v1/impersonation/sessions/active. This returns all sessions initiated by the authenticated admin.