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 e PATCH | Atualizar parcialmente grupo de usuários 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.
Um token de acesso OAuth 2.0 válido. Para mais informações, acesse Como autenticar uma aplicação 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.