Ending Impersonation Sessions

Impersonation sessions can be terminated through normal end, force-end by another admin, or automatic expiry. When a session ends, the impersonation token is revoked and the session's end time and reason are recorded in the audit trail.

Normal Session End

The admin who initiated the session can end it by calling:

POST /api/v1/impersonation/:sessionId/end

Only the admin who started the session can end it through this endpoint.

Force-End by Admin

Platform administrators can force-end any active impersonation session:

POST /api/v1/impersonation/sessions/:sessionId/force-end

This endpoint requires ADMIN role and can terminate sessions started by other admins. The force-end is recorded separately in the audit trail.

Revoke All Sessions for a User

To revoke all impersonation sessions involving a specific user (either as admin or target):

DELETE /api/v1/impersonation/users/:userId/sessions

Returns {"revokedCount": 2} with the number of sessions that were revoked.

Automatic Expiry

Sessions have a configurable maximum duration (default: 60 minutes). When a session expires:

1. The impersonation token becomes invalid
2. The session status is set to EXPIRED
3. An audit event is recorded with reason "Session expired"
4. Any subsequent API calls with the expired token return 401

Session Validation

To check if a session is still valid without ending it:

GET /api/v1/impersonation/sessions/:sessionId/validate

Returns:

{
  "valid": true,
  "sessionId": "imp-session-uuid"
}

A session is considered invalid when it has been ended, force-ended, or expired.

Post-Termination

After a session ends, the admin's original token remains valid. The admin returns to operating under their own identity. All actions performed during the impersonation session remain recorded in the audit trail with both the admin and target user's identifiers.