--- title: "GET | List all user groups" slug: "api-v2-get-list-all-user-groups" updated: 2026-11-03T14:57:58Z published: 2026-11-03T14:57:58Z canonical: "docs.senhasegura.io/api-v2-get-list-all-user-groups" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.senhasegura.io/llms.txt > Use this file to discover all available pages before exploring further. # 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](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a). - A valid OAuth 2.0 access token. For more information, access [How to authenticate an application in A2A](/v4-2/docs/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](/v4-2/docs/api-v2-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](/v4-2/docs/api-v2-conventions-and-shared-behaviors).