---
title: "GET | List a user group by [id]"
slug: "api-v2-get-list-a-user-group"
updated: 2026-11-03T14:57:58Z
published: 2026-11-03T14:57:58Z
canonical: "docs.senhasegura.io/api-v2-get-list-a-user-group"
---

> ## 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 a user group by [id]

## Description

Retrieve the full detail of a single user group by its identification code. The response carries the group attributes, the actions available in its current state, and a strong entity tag in the `ETag` header.

Send this request before any update, the `ETag` value is what [PUT | Update user group](/v4-2/docs/api-v2-put-update-user-group) and [PATCH | Partially update user group](/v4-2/docs/api-v2-patch-update-user-group) require in the `If-Match` header.

---

## 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).

---

## Request

`GET` `/api/v2/iam/user-groups/{id}`

### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Yes | Unique identification code of the user group. |

### Headers

| Header | Required | Description |
| --- | --- | --- |
| `If-None-Match` | No | Entity tag from a previous response, used for cache validation. When the value matches the current entity tag, the server returns `304 Not Modified` with no body. |

### Query parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `fields` | string | Comma-separated list of keys to return. Allowed values: `id`, `user_group`, `user_group.name`, `user_group.active`, `user_group.description`, `user_group.external_id`, `user_group.created_at`, `user_group.updated_at`. |

---

### Example request

`GET` `{{url}}/api/v2/iam/user-groups/7`

---

## Response

```
HTTP/1.1 200 OK
ETag: "v1"
X-Request-Id: 7f3c1a90-2c4e-4b1a-9f5e-0a2b7c9d1e34
```

### Example response body

```
{
  "data": {
    "id": "7",
    "user_group": {
      "name": "Payments",
      "active": true,
      "description": "Finance team group",
      "external_id": null,
      "created_at": "2026-04-01T12:00:00+00:00",
      "updated_at": "2026-04-15T09:30:00+00:00"
    }
  },
  "meta": {
    "links": {
      "self": "/api/v2/iam/user-groups/7"
    },
    "actions": {
      "users.list": "/api/v2/iam/user-groups/7/users",
      "access-policies.list": "/api/v2/iam/user-groups/7/access-policies",
      "deactivate": "/api/v2/iam/user-groups/7/deactivate"
    }
  }
}
```

---

## Response body fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | object | The requested user group. |
| `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.description` | string | Description of the user group. Returns `null` when not provided. |
| `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 | Resource metadata. |
| `meta.links.self` | string | Path of the user group. |
| `meta.actions` | object | Actions available for the group in its current state. An active group offers `deactivate`, an inactive group offers `activate`. |
| `meta.actions.users.list` | string | Path used to list the members of the group. |
| `meta.actions.access-policies.list` | string | Path used to list the access policy bindings of the group. |

---

## Errors

| HTTP code | Message | Possible cause | Solution |
| --- | --- | --- | --- |
| `401` | `api.auth.unauthorized` | The access token is missing, invalid, or has expired. | Request a new access token. |
| `404` | `api.resource.not_found` | The user group does not exist, or it is outside the scope of the authorization. | Check the identification code and the authorization scope. |
| `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**. |
| `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. |

              Info

              

A `404` response also covers groups that exist but are outside the caller's tenant or authorization scope. For the full `403` versus `404` policy, access [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors).