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.