GET | List all user groups

Description

List the user groups registered on the platform. The response is paginated and supports global search, sorting, field projection, and filters by name, active state, and external identifier.

Filtering by external identifier is what lets an automation resolve which user group corresponds to a given Active Directory or LDAP group without listing every group and filtering on the client side.

Prerequisites

An application with the Users authorization granted by the administrator in A2A. For more information, access How to manage authorizations in A2A.
A valid OAuth 2.0 access token. For more information, access How to authenticate an application in A2A.

Info

An access token carries only the authorizations that existed when it was generated. After the administrator enables the Users authorization, generate a new token for the application, an existing token will not gain the new authorization.

Request

GET /api/v2/iam/user-groups

Query parameters

Parameter	Type	Description
`page`	integer	1-indexed page number. Defaults to `1`.
`limit`	integer	Page size. Defaults to `50`. The maximum is `200`.
`sort_by`	string	Comma-separated list of fields, as `<field>`, `<field>:asc`, or `<field>:desc`. The direction is optional and defaults to `asc`. Allowed fields: `id`, `user_group.name`, `user_group.active`, `user_group.created_at`, `user_group.updated_at`.
`fields`	string	Comma-separated list of keys to return. Allowed values: `id`, `user_group.name`, `user_group.active`, `user_group.external_id`, `user_group.created_at`, `user_group.updated_at`.
`search`	string	Free-text match on `user_group.name`, `user_group.active`, and `user_group.external_id`. The value matches when a field contains it. Separate terms with spaces to require all of them.
`user_group.name`	string	Filters by group name. Exact match.
`user_group.active`	boolean	Filters by active state. Accepts `true` or `false`.
`user_group.external_id`	string	Filters by external identifier, assigned by the LDAP synchronization. Exact match.

Each filter also accepts the suffixes _contains, _starts_with, and _ends_with for a partial match, for example user_group.name_contains=pay. Separate values with a comma to match any of them. Repeat a filter to require all of its values.

Filter names must carry the user_group. prefix. A parameter without it, such as name, is unknown and returns 400.

When the request does not send sort_by, the order of the results is not guaranteed.

Attention

The listing includes deleted and deactivated groups. To list only active groups, filter with user_group.active=true.

Example request

GET {{url}}/api/v2/iam/user-groups?page=1&limit=50&user_group.active=true

Response

HTTP/1.1 200 OK
X-Request-Id: 7f3c1a90-2c4e-4b1a-9f5e-0a2b7c9d1e34
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599

The X-Request-Id header holds a per-request correlation code. Include it in support tickets so the Segura™ support team can locate the matching backend log entry.

Example response body

{
  "data": [
    {
      "id": "7",
      "user_group": {
        "name": "Payments",
        "active": true,
        "external_id": null,
        "created_at": "2026-04-01T12:00:00+00:00",
        "updated_at": "2026-04-15T09:30:00+00:00"
      }
    },
    {
      "id": "8",
      "user_group": {
        "name": "Engineering",
        "active": true,
        "external_id": "cn=eng,ou=groups,dc=example",
        "created_at": "2026-03-12T10:00:00+00:00",
        "updated_at": "2026-04-20T16:45:00+00:00"
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 50,
      "total_items": 64,
      "total_pages": 2
    },
    "links": {
      "self": "/api/v2/iam/user-groups?page=1&limit=50",
      "next": "/api/v2/iam/user-groups?page=2&limit=50"
    }
  }
}

Response body fields

The listing does not return the group's description. To read it, access GET | List a user group.

Field	Type	Description
`data`	array[object]	User groups on the current page.
`data[].id`	string	Unique identification code of the user group, assigned by Segura™.
`data[].user_group`	object	Attributes of the user group.
`data[].user_group.name`	string	Name of the user group.
`data[].user_group.active`	boolean	Indicates whether the user group is active.
`data[].user_group.external_id`	string	External identifier of the group in the LDAP or Active Directory source. Returns `null` when the group is not linked to an external group.
`data[].user_group.created_at`	datetime	Date and time when the user group was created.
`data[].user_group.updated_at`	datetime	Date and time of the last change to the user group.
`meta`	object	Listing metadata.
`meta.pagination`	object	Pagination state for the current request.
`meta.pagination.page`	integer	Current page number.
`meta.pagination.limit`	integer	Page size applied to the request.
`meta.pagination.total_items`	integer	Total number of user groups that match the request.
`meta.pagination.total_pages`	integer	Total number of pages available.
`meta.links`	object	Navigation links for the listing.
`meta.links.self`	string	Path of the current page.
`meta.links.next`	string	Path of the next page. Returned only when a next page exists.
`meta.links.prev`	string	Path of the previous page. Returned only when a previous page exists.

Errors

HTTP code	Message	Possible cause	Solution
`400`	`api.request.bad_request`	The request carries an unknown query parameter, such as a filter without the `user_group.` prefix.	Remove the unrecognized parameter, or add the `user_group.` prefix, and resend the request.
`401`	`api.auth.unauthorized`	The access token is missing, invalid, or has expired.	Request a new access token.
`422`	`api.request.invalid_param`	A filter has an invalid value, such as `user_group.active=yes`.	Correct the value and resend the request.
`422`	`api.validation.invalid_field`	The `fields` parameter references a key that is not part of the schema.	Use only the allowed values listed in Query parameters.
`422`	`api.sort.invalid_direction`	A `sort_by` segment declares a direction other than `asc` or `desc`.	Write each segment as `<field>`, `<field>:asc`, or `<field>:desc`.
`422`	`api.sort.invalid_field`	A `sort_by` segment references a field that cannot be sorted.	Use only the sort fields listed in Query parameters.
`422`	`api.pagination.limit.exceeded`	The `limit` value is greater than `200`.	Send a `limit` of `200` or less.
`429`	`api.rate_limit_exceeded`	The request rate limit was exceeded.	Wait the number of seconds returned in the `Retry-After` header and try again.

For authentication error messages and the 403 versus 404 policy, access API v2 - Conventions and shared behaviors.