/impersonate - Start impersonation (permission-based access)

POST /impersonate
Bearer auth

Allows users with impersonate:users permission (Super Admin role) or Owner organization role to impersonate another user, but only if that user has active consent enabled. The impersonation token duration will match the user's consent settings.

application/json

Body Required

  • user_id string Required

    ID of the user to impersonate

Responses

  • 200 application/json

    Impersonation started successfully

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object
      Hide data attributes Show data attributes object
      • token string

        Impersonation JWT token with custom duration

      • expires_in integer

        Token expiration time in seconds (matches user consent)

      • session_id string

        Unique session ID for audit tracking

      • is_impersonating boolean

        Flag indicating impersonation is active

      • impersonated_user object
        Hide impersonated_user attributes Show impersonated_user attributes object
        • id string

          User account ID

        • logto_id string | null

          Logto user ID

        • username string

          Username

        • email string(email)

          Email address

        • name string

          Full name

        • phone string | null

          Phone number

        • organization object

          Organization information (null when not assigned to an organization)

          Hide organization attributes Show organization attributes object
          • id string

            Local database organization ID

          • logto_id string

            Logto organization ID

          • name string

            Organization name

        • roles array[object]

          User roles with names

          Hide roles attributes Show roles attributes object
          • id string

            Role ID

          • name string

            Role name

        • custom_data object

          Custom user data

          Additional properties are allowed.

        • created_at string(date-time)

          Account creation timestamp

        • updated_at string(date-time)

          Last update timestamp

        • logto_synced_at string(date-time) | null

          Last Logto synchronization timestamp

        • latest_login_at string(date-time) | null

          Timestamp of the last successful login via /auth/exchange endpoint. NULL means user has never logged in.

        • deleted_at string(date-time) | null

          Soft delete timestamp (null if not deleted)

        • suspended_at string(date-time) | null

          Suspension timestamp (null if not suspended)

        • can_be_impersonated boolean

          Whether this user can currently be impersonated (only shown for users with impersonation permissions, based on active consent)

      • impersonator object
        Hide impersonator attributes Show impersonator attributes object
        • id string

          User account ID

        • logto_id string | null

          Logto user ID

        • username string

          Username

        • email string(email)

          Email address

        • name string

          Full name

        • phone string | null

          Phone number

        • organization object

          Organization information (null when not assigned to an organization)

          Hide organization attributes Show organization attributes object
          • id string

            Local database organization ID

          • logto_id string

            Logto organization ID

          • name string

            Organization name

        • roles array[object]

          User roles with names

          Hide roles attributes Show roles attributes object
          • id string

            Role ID

          • name string

            Role name

        • custom_data object

          Custom user data

          Additional properties are allowed.

        • created_at string(date-time)

          Account creation timestamp

        • updated_at string(date-time)

          Last update timestamp

        • logto_synced_at string(date-time) | null

          Last Logto synchronization timestamp

        • latest_login_at string(date-time) | null

          Timestamp of the last successful login via /auth/exchange endpoint. NULL means user has never logged in.

        • deleted_at string(date-time) | null

          Soft delete timestamp (null if not deleted)

        • suspended_at string(date-time) | null

          Suspension timestamp (null if not suspended)

        • can_be_impersonated boolean

          Whether this user can currently be impersonated (only shown for users with impersonation permissions, based on active consent)
  • 400 application/json

    Bad request (cannot impersonate yourself, user not found, etc.)

    Hide response attributes Show response attributes object
    • code integer

      HTTP error code

    • message string

      Error message

    • data object
      Hide data attributes Show data attributes object
      • type string

        Type of error

        Values are validation_error or external_api_error.

      • errors array[object]
        Hide errors attributes Show errors attributes object
        • key string

          Field name that failed validation

        • message string

          Error code or message

        • value string

          Value that failed validation

      • details

        Additional error details
  • 403 application/json

    Forbidden (insufficient permissions for impersonation, or already impersonating)

    Hide response attributes Show response attributes object
    • code integer

      HTTP error code

    • message string

      Error message

    • data object
      Hide data attributes Show data attributes object
      • type string

        Type of error

        Values are validation_error or external_api_error.

      • errors array[object]
        Hide errors attributes Show errors attributes object
        • key string

          Field name that failed validation

        • message string

          Error code or message

        • value string

          Value that failed validation

      • details

        Additional error details
  • 401 application/json

    Unauthorized - invalid or missing token

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object | null
POST /impersonate 
curl \
 --request POST 'https://api.your-domain.com/api/impersonate' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"user_id":"user-uuid-here"}'
Request examples 
{
  "user_id": "user-uuid-here"
}
Response examples (200) 
{
  "code": 200,
  "message": "impersonation started successfully",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 86400,
    "session_id": "session-uuid-here",
    "is_impersonating": true,
    "impersonated_user": {
      "id": "usr_123456789",
      "logto_id": "user_abc123def456",
      "username": "john.doe",
      "email": "john@example.com",
      "name": "John Doe",
      "phone": "+39 333 123456",
      "organization": {
        "id": "12345678-1234-1234-1234-123456789abc",
        "logto_id": "org_123456789",
        "name": "ACME Corp"
      },
      "roles": [
        {
          "id": "rol_admin_123",
          "name": "Admin"
        }
      ],
      "custom_data": {
        "position": "Senior Developer",
        "department": "IT"
      },
      "created_at": "2025-06-20T14:30:00Z",
      "updated_at": "2025-06-21T10:45:00Z",
      "logto_synced_at": "2025-06-21T10:45:00Z",
      "latest_login_at": "2025-06-21T15:30:45Z",
      "deleted_at": "2025-05-04T09:42:00Z",
      "suspended_at": "2025-05-04T09:42:00Z",
      "can_be_impersonated": true
    },
    "impersonator": {
      "id": "usr_123456789",
      "logto_id": "user_abc123def456",
      "username": "john.doe",
      "email": "john@example.com",
      "name": "John Doe",
      "phone": "+39 333 123456",
      "organization": {
        "id": "12345678-1234-1234-1234-123456789abc",
        "logto_id": "org_123456789",
        "name": "ACME Corp"
      },
      "roles": [
        {
          "id": "rol_admin_123",
          "name": "Admin"
        }
      ],
      "custom_data": {
        "position": "Senior Developer",
        "department": "IT"
      },
      "created_at": "2025-06-20T14:30:00Z",
      "updated_at": "2025-06-21T10:45:00Z",
      "logto_synced_at": "2025-06-21T10:45:00Z",
      "latest_login_at": "2025-06-21T15:30:45Z",
      "deleted_at": "2025-05-04T09:42:00Z",
      "suspended_at": "2025-05-04T09:42:00Z",
      "can_be_impersonated": true
    }
  }
}
Response examples (400) 
{
  "code": 400,
  "message": "Cannot impersonate yourself"
}
{
  "code": 400,
  "message": "Target user not found or inaccessible"
}
{
  "code": 400,
  "message": "Target user has not provided consent for impersonation or consent has expired"
}
Response examples (403) 
{
  "code": 403,
  "message": "Insufficient permissions to impersonate users"
}
{
  "code": 403,
  "message": "Cannot impersonate while already impersonating another user. Exit current impersonation first."
}
Response examples (401) 
{
  "code": 401,
  "message": "invalid token",
  "data": {}
}