---
title: "GET | Consultar um grupo de usuários"
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 | Consultar um grupo de usuários

## Descrição

Consulte o detalhe completo de um grupo de usuários pelo seu código de identificação. A resposta carrega os atributos do grupo, as ações disponíveis em seu estado atual e uma entity tag forte no cabeçalho `ETag`.

Envie esta requisição antes de qualquer atualização, o valor de `ETag` é o que [PUT | Atualizar grupo de usuários](/v4-2/docs/api-v2-put-update-user-group) e [PATCH | Atualizar parcialmente grupo de usuários](/v4-2/docs/api-v2-patch-update-user-group) exigem no cabeçalho `If-Match`.

---

## Pré-requisitos

- Uma aplicação com a autorização **Users** concedida pelo administrador no A2A. Para mais informações, acesse [Como gerenciar autorizações no A2A API v2](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a).
- Um token de acesso OAuth 2.0 válido. Para mais informações, acesse [Como autenticar uma aplicação A2A](/v4-2/docs/how-to-authenticate-an-application-in-a2a).

---

## Requisição

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

### Parâmetros de path

| Parâmetro | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | integer | Sim | Código de identificação único do grupo de usuários. |

### Cabeçalhos

| Cabeçalho | Obrigatório | Descrição |
| --- | --- | --- |
| `If-None-Match` | Não | Entity tag de uma resposta anterior, usada para validação de cache. Quando o valor corresponde à entity tag atual, o servidor retorna `304 Not Modified` sem corpo. |

### Parâmetros de query

| Parâmetro | Tipo | Descrição |
| --- | --- | --- |
| `fields` | string | Lista de chaves separadas por vírgula a retornar. Valores permitidos: `id`, `user_group`, `user_group.name`, `user_group.active`, `user_group.description`, `user_group.external_id`, `user_group.created_at`, `user_group.updated_at`. |

---

### Exemplo de requisição

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

---

## Resposta

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

### Exemplo de corpo de resposta

```
{
  "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"
    }
  }
}
```

---

## Campos do corpo de resposta

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `data` | object | O grupo de usuários solicitado. |
| `data.id` | string | Código de identificação único do grupo de usuários, atribuído pela Segura™. |
| `data.user_group` | object | Atributos do grupo de usuários. |
| `data.user_group.name` | string | Nome do grupo de usuários. |
| `data.user_group.active` | boolean | Indica se o grupo de usuários está ativo. |
| `data.user_group.description` | string | Descrição do grupo de usuários. Retorna `null` quando não informada. |
| `data.user_group.external_id` | string | Identificador externo do grupo na origem LDAP ou Active Directory. Retorna `null` quando o grupo não está vinculado a um grupo externo. |
| `data.user_group.created_at` | datetime | Data e hora de criação do grupo de usuários. |
| `data.user_group.updated_at` | datetime | Data e hora da última alteração do grupo de usuários. |
| `meta` | object | Metadados do recurso. |
| `meta.links.self` | string | Caminho do grupo de usuários. |
| `meta.actions` | object | Ações disponíveis para o grupo em seu estado atual. Um grupo ativo oferece `deactivate`, um grupo inativo oferece `activate`. |
| `meta.actions.users.list` | string | Caminho usado para listar os membros do grupo. |
| `meta.actions.access-policies.list` | string | Caminho usado para listar os vínculos de política de acesso do grupo. |

---

## Erros

| Código HTTP | Mensagem | Possível causa | Solução |
| --- | --- | --- | --- |
| `401` | `api.auth.unauthorized` | O token de acesso está ausente, inválido ou expirou. | Solicite um novo token de acesso. |
| `404` | `api.resource.not_found` | O grupo de usuários não existe, ou está fora do escopo da autorização. | Verifique o código de identificação e o escopo da autorização. |
| `422` | `api.validation.invalid_field` | O parâmetro `fields` referencia uma chave que não faz parte do schema. | Use apenas os valores permitidos listados em **Parâmetros de query**. |
| `429` | `api.rate_limit_exceeded` | O limite de requisições foi excedido. | Aguarde o número de segundos retornado no cabeçalho `Retry-After` e tente novamente. |

              Info

              

Uma resposta `404` também cobre grupos que existem, mas estão fora do tenant ou do escopo de autorização do chamador. Para a política completa de `403` versus `404`, acesse [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors).