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 and ipv6_address.

  Minimum length is 1.

• sort_by string

  Field to sort distributors by

  Values are name, description, created_at, updated_at, suspended_at, or creator_name.

• sort_direction string

  Sort direction

  Values are asc or desc. Default value is asc.

• status array[string]

  Filter organizations by status. Supports multiple values.

  • enabled: not suspended and not deleted
  • suspended: suspended but not deleted
  • deleted: soft-deleted

  When "deleted" is combined with other statuses, both deleted and non-deleted matching records are returned.

  Values are enabled, suspended, or deleted.

• created_by array[string]

  Filter organizations 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 organization creator (custom_data.createdByUser). Supports multiple values for checkbox filtering. Allowed values come from GET /api/filters/{distributors|resellers|customers}.

  Examples:

  • ?created_by=kyfy0tlnlk3l - matches organizations created by user with ID kyfy0tlnlk3l
  • ?created_by=obhdyclbfx4t - matches organizations created by users in organization obhdyclbfx4t
  • ?created_by=kyfy0tlnlk3l&created_by=obhdyclbfx4t - matches organizations created by the user OR by users in the organization
• organization_id array[string]

  Filter by owning organization Logto ID (custom_data.createdBy, the ownership key RBAC visibility walks). Supports multiple values; combine with include_hierarchy to cover a whole subtree. Results always stay within the caller's RBAC scope.

• include_hierarchy boolean

  When true (and organization_id is provided), each organization_id is expanded to the organization plus all its descendants (a distributor's resellers and their customers, a reseller's customers) before filtering

  Default value is false.

• include_counts string

  Which inline counters to compute for every row. They are not free, and they are not all equally expensive, so the caller asks for the tier it needs. Counters that are not requested are omitted from the response objects entirely.

  • omitted: no counters. What an integration that only wants the rows should send - listing the organizations then costs a single indexed page read.
  • true: systems_count, customers_count, resellers_count and legacy_systems_count. These are the counters the portal lists render, and they are all indexed lookups.
  • all: also applications_count. On the reseller list this is expensive - the organization set of a reseller row is the reseller plus its customers, a correlated subquery the planner cannot push into the applications index, so every row rescans all the certified applications. Expect seconds on a large tenant, and prefer GET /resellers/{id}/stats when you need the number for one organization.

  Values are true or all.

Responses

• 200 application/json

  Distributors retrieved successfully

  Hide response attributes Show response attributes object

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

    • distributors array[object]

      Organization with inline count statistics, returned in list responses.

      Every counter below is opt-in through the include_counts parameter and is omitted from the object when it was not requested, so a list read without include_counts returns the plain Organization fields only.

      Hide distributors attributes Show distributors attributes object

      Organization with inline count statistics, returned in list responses.

      Every counter below is opt-in through the include_counts parameter and is omitted from the object when it was not requested, so a list read without include_counts returns the plain Organization fields only.

      • id string

        Database UUID of the organization

      • logto_id string

        Logto organization ID (use this value for assignment operations)

      • name string

        Organization name

      • description string

        Organization description

      • custom_data object

        Custom organization data

        Additional properties are allowed.

      • third_party_apps array[string]

        Distributors only. The portals the distributor's resellers and customers may use on the dashboard (application names as registered in Logto); the distributor's own users are not bound by it. Always present on a distributor, as an empty array when no portal is enabled for the subtree. Absent on resellers and customers.

      • suspended_at string(date-time) | null

        Timestamp when the organization was suspended. NULL means enabled, non-NULL means blocked/suspended.

      • suspended_by_org_id string | null

        Organization ID that caused cascade suspension (for resellers and customers only). NULL means directly suspended or not suspended. When set, the entity can only be reactivated by the parent organization that initiated the cascade.

      • rebranding_enabled boolean

        Whether rebranding is active for this organization (directly or inherited from parent)

      • rebranding_org_id string | null

        The organization ID that provides the rebranding (the org where rebranding is configured). Only present when rebranding_enabled is true.

      • created_by object

        Snapshot of the user who created an organization (distributor, reseller or customer). The user identity fields are point-in-time; organization_name is kept in sync when the referenced organization is renamed.

        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.

      • promoted_from object

        Trace of the promotion that gave the organization its level. Distributors only, and only those promoted from reseller level (PATCH /resellers/{id}/promote) - omitted for an organization created at its level.

        Hide promoted_from attributes Show promoted_from attributes object

        • level string

          The organization level the promotion moved up from

        • at string(date-time)

          When the promotion ran

        • detached_from_organization_id string

          Logto ID of the organization that manages the promoted organization at its old level and drops it from its scope. Omitted when the organization carried no createdBy.

        • by object

          Snapshot of the user who ran the promotion

          Hide by attributes Show 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.

      • systems_count integer

        Number of systems in this organization. Requires include_counts=true.

      • resellers_count integer

        Number of resellers created by this distributor (distributors only). Requires include_counts=true.

      • customers_count integer

        Number of customers in the hierarchy (distributors and resellers only). Requires include_counts=true.

      • legacy_systems_count integer

        Systems of this organization still on the old my, pushed per organization by the legacy sync. Deliberately not included in systems_count: that one answers "what does this portal manage". Distributors and resellers only, and requires include_counts=true. Transitional field.

      • applications_count integer

        Number of certified, user-facing applications (certification_level 4 or 5) in the hierarchy. An unassigned application counts under the organization of the system hosting it.

        Requires include_counts=all, and on the reseller list that is the slow option - see the parameter description. GET /{resource}/{id}/stats returns the same number for a single organization without the cost.

    • 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