User Impersonation

Impersonation allows administrators to temporarily act as another user for support and debugging purposes.

Overview

User impersonation enables:

Debugging complex permission issues
Reproducing user-reported bugs
Verifying tenant configurations

[!CAUTION] Impersonation grants the admin the same access as the target user. Every impersonation session is logged with HIGH severity in the platform audit log.

Endpoints

Method	Path	Description
`POST`	`/api/platform/impersonate`	Create impersonation token

POST /api/platform/impersonate

Generate a short-lived impersonation token for a target user.

Authorization: Platform Owner OR Organization Admin (scoped to their own org)

Request Body

Field	Type	Required	Description
`user_id`	`string`	Yes	UUID of the user to impersonate
`reason`	`string`	Yes	Reason for impersonation (audited)

Example Request

curl -X POST https://sso.example.com/api/platform/impersonate \
  -H "Authorization: Bearer {admin_jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "reason": "Investigating login failure ticket #998"
  }'

Response (200 OK)

{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "target_user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "is_platform_owner": false,
    "org_id": "org-uuid",
    "org_name": "Acme Corp"
  },
  "actor_user": {
    "id": "admin-uuid",
    "email": "admin@example.com",
    "is_platform_owner": true
  }
}

Security Context

Token TTL: Impersonation tokens are extremely short-lived (15 minutes).
Audit Trail: A HIGH severity audit log entry is created including the actor, target, reason, and timestamp.
Permissions:
- Platform Owners can impersonate any user on the system.
- Organization Admins can only impersonate users that are members of organizations they manage.
No Refresh: Impersonation sessions do not provide refresh tokens.

Usage

The returned token is a standard JWT that can be used in the Authorization: Bearer header for any API calls. The token includes claims indicating it is an impersonation session, which are tracked by the platform’s audit system for all subsequent actions.