Query parameters

• page integer

  Page number

  Minimum value is 1. Default value is 1.

• page_size integer

  Items per page

  Minimum value is 1, maximum value is 200. Default value is 20.

• search string

  Search term. For organizations (distributors, resellers, customers), searches across name, description, and all custom_data fields (vat, address, city, contact, email, phone, language, notes, etc.). For systems, also searches across ipv4_address, ipv6_address and the organization name.

  Minimum length is 1.

• sort_by string

  Field to sort users by

  Values are name, email, username, created_at, updated_at, latest_login_at, organization, creator_name, or status.

• sort_direction string

  Sort direction

  Values are asc or desc. Default value is asc.

• organization_id array[string]

  Filter by organization logto_id. Supports multiple values.

• status array[string]

  Filter by user status. Supports multiple values, OR'd together.

  • enabled: not suspended and not deleted
  • suspended: suspended but not deleted
  • deleted: soft-deleted
  • no_login: virtual status matching accounts that never signed in (latest_login_at IS NULL)

  "no_login" is additive rather than exclusive: such an account is also enabled or suspended, so it matches both filters. Selecting it alone yields exactly the users flagged with the "no login" badge in the UI. Deleted accounts stay hidden unless "deleted" is selected.

  Values are enabled, suspended, deleted, or no_login.

• role array[string]

  Filter by user role ID. Supports multiple values.

• created_by array[string]

  Filter users by creator user ID or creator organization ID (exact match). Each provided ID is checked against both the user_id and organization_id fields of the user creator snapshot. Supports multiple values for checkbox filtering. Allowed values come from GET /api/filters/users.

Responses

• 200 application/json

  Users retrieved successfully

  Hide response attributes Show response attributes object

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

    • users array[object]
      Hide users attributes Show users 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

        • type string

          Organization type in the business hierarchy

          Values are owner, distributor, reseller, or customer.

      • 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)

      • created_by object

        Point-in-time snapshot of the user who created this user (omitted on accounts created before the snapshot was introduced). Display/filter only - RBAC is by organization.

        Hide created_by attributes Show created_by attributes object

        • user_id string

          Logto ID of the user who created the organization

        • username string

          Username of the creator

        • name string

          Full name of the creator

        • email string

          Email of the creator

        • organization_id string

          Organization ID the creator belongs to

        • organization_name string

          Organization name the creator belongs to

        • organization_type string

          Current level of the creator's organization, resolved on every read (never stored), so a promoted organization is reported at its current level. The Owner organization is reported as "owner", the same value the organization_type of users and systems carries for it, so a client draws it with the same icon. Omitted only for a deleted organization, which has no level to assert and no detail page to link to.

          Values are distributor, reseller, customer, or owner.

        • on_behalf_of boolean

          True when the organization was attributed to a different organization via created_by_organization_id (the user acted on behalf of organization_name rather than belonging to it). Omitted when false.

      • can_be_impersonated boolean

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

      • has_avatar boolean

        Whether the user has a profile picture stored. False means GET /public/users/{logto_id}/avatar has nothing to serve, so clients can render initials without issuing the request.

    • pagination object
      Hide pagination attributes Show pagination attributes object

      • page integer

        Current page number

        Minimum value is 1.

      • page_size integer

        Number of items per page

        Minimum value is 1, maximum value is 200.

      • total_count integer

        Total number of items

        Minimum value is 0.

      • total_pages integer

        Total number of pages

        Minimum value is 0.

      • has_next boolean

        Whether there is a next page

      • has_prev boolean

        Whether there is a previous page

      • next_page integer | null

        Next page number if available

      • prev_page integer | null

        Previous page number if available

      • sort_by string | null

        Field used for sorting

      • sort_direction string | null

        Sort direction

        Values are asc or desc.

• 401 application/json

  Unauthorized - invalid or missing token

  Hide response attributes Show response attributes object

  • code integer
  • message string
  • data object | null
• 403 application/json

  Forbidden - insufficient permissions

  Hide response attributes Show response attributes object

  • code integer
  • message string
  • data object | null