GET | Listar todos os grupos de usuários

Descrição

Liste os grupos de usuários cadastrados na plataforma. A resposta é paginada e aceita busca global, ordenação, projeção de campos e filtros por nome, estado ativo e identificador externo.

O filtro por identificador externo é o que permite a uma automação identificar qual grupo de usuários corresponde a um determinado grupo do Active Directory ou LDAP, sem listar todos os grupos e filtrar no lado do cliente.

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.

Info

Um token de acesso carrega apenas as autorizações que existiam no momento em que foi gerado. Depois que o administrador habilitar a autorização Users, gere um novo token para a aplicação. Um token existente não passa a ter a nova autorização.

Requisição

GET /api/v2/iam/user-groups

Parâmetros de query

Parâmetro	Tipo	Descrição
`page`	integer	Número da página, indexado a partir de 1. O padrão é `1`.
`limit`	integer	Tamanho da página. O padrão é `50`. O máximo é `200`.
`sort_by`	string	Lista de campos separados por vírgula, no formato `<campo>`, `<campo>:asc` ou `<campo>:desc`. A direção é opcional e o padrão é `asc`. Campos permitidos: `id`, `user_group.name`, `user_group.active`, `user_group.created_at`, `user_group.updated_at`.
`fields`	string	Lista de chaves separadas por vírgula a retornar. Valores permitidos: `id`, `user_group.name`, `user_group.active`, `user_group.external_id`, `user_group.created_at`, `user_group.updated_at`.
`search`	string	Busca por texto livre em `user_group.name`, `user_group.active` e `user_group.external_id`. O valor corresponde quando um campo o contém. Separe os termos com espaços para exigir todos eles.
`user_group.name`	string	Filtra pelo nome do grupo. Correspondência exata.
`user_group.active`	boolean	Filtra pelo estado ativo. Aceita `true` ou `false`.
`user_group.external_id`	string	Filtra pelo identificador externo, atribuído pela sincronização LDAP. Correspondência exata.

Cada filtro também aceita os sufixos _contains, _starts_with e _ends_with para uma correspondência parcial, por exemplo user_group.name_contains=pay. Separe os valores com vírgula para corresponder a qualquer um deles. Repita um filtro para exigir todos os seus valores.

Os nomes dos filtros precisam ter o prefixo user_group.. Um parâmetro sem ele, como name, é desconhecido e retorna 400.

Quando a requisição não envia sort_by, a ordem dos resultados não é garantida.

Atenção

A listagem inclui grupos excluídos e desativados. Para listar somente os grupos ativos, filtre com user_group.active=true.

Exemplo de requisição

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

Resposta

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

O cabeçalho X-Request-Id carrega um código de correlação por requisição. Inclua-o em chamados de suporte para que o time de suporte Segura™ localize o registro correspondente no log do backend.

Exemplo de corpo de resposta

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

Campos do corpo de resposta

A listagem não retorna a description do grupo. Para consultá-la, acesse GET | Consultar um grupo de usuários.

Campo	Tipo	Descrição
`data`	array[object]	Grupos de usuários na página atual.
`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.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 da listagem.
`meta.pagination`	object	Estado da paginação para a requisição atual.
`meta.pagination.page`	integer	Número da página atual.
`meta.pagination.limit`	integer	Tamanho de página aplicado à requisição.
`meta.pagination.total_items`	integer	Número total de grupos de usuários que correspondem à requisição.
`meta.pagination.total_pages`	integer	Número total de páginas disponíveis.
`meta.links`	object	Links de navegação da listagem.
`meta.links.self`	string	Caminho da página atual.
`meta.links.next`	string	Caminho da próxima página. Retornado somente quando existe uma próxima página.
`meta.links.prev`	string	Caminho da página anterior. Retornado somente quando existe uma página anterior.

Erros

Código HTTP	Mensagem	Possível causa	Solução
`400`	`api.request.bad_request`	A requisição carrega um parâmetro de query desconhecido, como um filtro sem o prefixo `user_group.`.	Remova o parâmetro não reconhecido, ou adicione o prefixo `user_group.`, e reenvie a requisição.
`401`	`api.auth.unauthorized`	O token de acesso está ausente, inválido ou expirou.	Solicite um novo token de acesso.
`422`	`api.request.invalid_param`	Um filtro tem um valor inválido, como `user_group.active=yes`.	Corrija o valor e reenvie a requisiçã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.
`422`	`api.sort.invalid_direction`	Um segmento de `sort_by` declara uma direção diferente de `asc` ou `desc`.	Escreva cada segmento como `<campo>`, `<campo>:asc` ou `<campo>:desc`.
`422`	`api.sort.invalid_field`	Um segmento de `sort_by` referencia um campo que não pode ser ordenado.	Use apenas os campos de ordenação listados em Parâmetros de query.
`422`	`api.pagination.limit.exceeded`	O valor de `limit` é maior que `200`.	Envie um `limit` de `200` ou menos.
`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.

Para as mensagens de erro de autenticação e a política de 403 versus 404, acesse API v2 - Convenções e comportamentos compartilhados.