MATIH Platform is in active MVP development. Documentation reflects current implementation status.
6. Identity & Access Management
Impersonation
Audit Trail

Impersonation Audit Trail

Every impersonation session is comprehensively audited. The audit trail captures session metadata, actions performed during impersonation, and provides query capabilities for compliance reporting. Audit endpoints require ADMIN role or audit:read authority.

Audit Data Captured

Each impersonation session records the following:

FieldDescription
Session IDUnique identifier for the impersonation session
Admin userThe administrator who initiated the session
Target userThe user being impersonated
ReasonThe stated justification for impersonation
Ticket referenceOptional support ticket or incident reference
IP addressThe admin's IP address at session start
User agentThe admin's browser or client identifier
Start timeWhen the session was created
End timeWhen the session was terminated
End reasonHow the session ended (normal, forced, expired)
ActionsList of actions performed during the session

Recording Actions

During an active impersonation session, API calls can record significant actions for the audit trail:

POST /api/v1/impersonation/sessions/:sessionId/record-action
{
  "action": "Viewed BI dashboard 'Monthly Revenue Summary'"
}

The action field has a maximum length of 200 characters.

Querying Audit History

Paginated history for the tenant:

GET /api/v1/impersonation/audit?page=0&size=20

Time-range query:

GET /api/v1/impersonation/audit/range?start=2026-01-01T00:00:00Z&end=2026-02-01T00:00:00Z

Both endpoints return paginated SessionInfo objects.

Impersonation Statistics

The statistics endpoint provides aggregate metrics for compliance reporting:

GET /api/v1/impersonation/stats

Returns ImpersonationStats including:

MetricDescription
Total sessionsAll-time session count
Active sessionsCurrently active sessions
Average durationMean session length in minutes
Sessions by adminBreakdown by admin user
Sessions by monthMonthly trend data

Compliance Integration

The impersonation audit trail integrates with the platform's centralized audit service. All impersonation events are forwarded to the audit pipeline with:

  • Event type: IMPERSONATION_START, IMPERSONATION_END, IMPERSONATION_ACTION
  • Severity: HIGH (all impersonation events are considered high-severity)
  • Retention: Impersonation audit records follow the tenant's data retention policy with a minimum of 365 days

Best Practices

  • Always provide a meaningful reason that explains the troubleshooting context
  • Include a ticketReference for traceability back to the support system
  • End sessions promptly once the investigation is complete
  • Review impersonation statistics regularly for anomalous patterns
Ending SessionsAPI Reference