User Impersonation

Platform owners can impersonate users for debugging and support purposes. All impersonation actions are fully audited.

Overview

User impersonation allows platform owners to:

Debug authentication issues from the user’s perspective
Verify permission and access configurations
Troubleshoot user-reported problems
Test organization or service configurations

[!CAUTION] Impersonation grants full access as the target user. All actions taken while impersonating are recorded in the audit log with the impersonator’s identity.

Endpoints

Method	Path	Description
`POST`	`/api/platform/impersonate/:user_id`	Start impersonation session

POST /api/platform/impersonate/:user_id

Create an impersonation session for the specified user.

Synopsis

Property	Value
Authentication	Required (Platform Owner JWT)
Authorization	Platform Owner only
Rate Limit	10/minute
Idempotent	No

Request Headers

Header	Value	Required
`Authorization`	`Bearer {platform_owner_jwt}`	Yes

Path Parameters

Parameter	Type	Description
`user_id`	`string`	Target user ID (UUID)

Request Body

Field	Type	Required	Description
`reason`	`string`	Yes	Reason for impersonation (logged)
`org_slug`	`string`	No	Organization context for token
`service_slug`	`string`	No	Service context for token

Example Request

curl -X POST https://sso.example.com/api/platform/impersonate/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Debugging login issue reported in ticket #12345",
    "org_slug": "acme-corp",
    "service_slug": "main-app"
  }'

Response (200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "660f9500-e30c-41d5-b827-557766551111",
  "impersonated_user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com"
  },
  "session_id": "impersonation-session-uuid",
  "expires_at": "2025-01-15T11:30:00Z",
  "audit_log_id": "audit-log-uuid"
}

Response Fields

Field	Type	Description
`access_token`	`string`	JWT token acting as impersonated user
`refresh_token`	`string`	Refresh token for session
`impersonated_user`	`object`	Basic info about impersonated user
`session_id`	`string`	Impersonation session ID
`expires_at`	`string`	Session expiration (1 hour max)
`audit_log_id`	`string`	Reference to audit log entry

Errors

Status	Code	Condition
`403`	`FORBIDDEN`	Not a platform owner
`404`	`NOT_FOUND`	User not found
`400`	`BAD_REQUEST`	Cannot impersonate platform owners

Impersonation Token Claims

Impersonation tokens include special claims:

{
  "sub": "target-user-uuid",
  "email": "user@example.com",
  "org": "acme-corp",
  "service": "main-app",
  "impersonator": "platform-owner-uuid",
  "impersonation_session": "session-uuid",
  "exp": 1705319400
}

Claim	Description
`impersonator`	Platform owner’s user ID
`impersonation_session`	Session ID for audit trail

Audit Trail

Every impersonation action is logged:

{
  "action": "impersonate_user",
  "platform_owner_id": "admin-uuid",
  "target_user_id": "user-uuid",
  "reason": "Debugging login issue reported in ticket #12345",
  "org_slug": "acme-corp",
  "service_slug": "main-app",
  "session_id": "impersonation-session-uuid",
  "created_at": "2025-01-15T10:30:00Z"
}

Actions taken while impersonating are also logged:

{
  "action": "update_profile",
  "user_id": "user-uuid",
  "impersonated_by": "admin-uuid",
  "impersonation_session": "session-uuid",
  "created_at": "2025-01-15T10:35:00Z"
}

Limitations

Restriction	Reason
Cannot impersonate platform owners	Security
Max session duration: 1 hour	Limited window
Cannot change password	Permanent action
Cannot disable MFA	Security-critical
Cannot delete account	Destructive action

Best Practices

Always provide a reason - Reasons are audited and may be reviewed
Use minimal context - Only request org/service context if needed
End sessions promptly - Logout when done debugging
Document findings - Reference audit log ID in support tickets