Skip to content

User Impersonation

Koldan's impersonation feature allows administrators and managers to view the platform as another user - useful for troubleshooting, support, and verifying user-specific configurations.

Quick Start

Add the X-Impersonate-User header to any authenticated API request:

curl -X GET "https://koldan.dixilang.com/api/v1/speech/files" \
  -H "Authorization: Bearer <your-admin-jwt>" \
  -H "X-Impersonate-User: <target-user-uuid>"

The response will contain exactly what the target user would see - their files, their permissions, their data.

Requirements

  • The calling user must have the admin:impersonate permission scope
  • The calling user's role hierarchy order must be ≥ the target user's (e.g., a Manager cannot impersonate an Admin)

Header Reference

Header Value Description
X-Impersonate-User UUID The user UUID to impersonate. Omit to make a normal (non-impersonated) request.

For gRPC, use the X-Impersonate-User metadata key.

Security Context During Impersonation

When impersonation is active:

  • User identity - the request is processed as the target user (e.g., file listings show the target user's files)
  • Permission scopes - re-resolved from the target user's role assignment, not the admin's

  • Audit trail - every impersonated request is logged under both the admin and target user identities, and preserved in the archive for longer than regular requests. What does not change:

  • Authentication - the admin's JWT remains valid and unmodified

  • Tenant - stays the same (cross-tenant impersonation is not allowed)

Error Responses

Code Reason
400 Invalid UUID or self-impersonation attempt
401 Not authenticated
403 Caller lacks admin:impersonate scope
403 Target user has a higher role than the caller