--- title: "GET | Listar todos os grupos de usuários" 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 | 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](/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). 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](/v4-2/docs/api-v2-get-list-a-user-group). | 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](/v4-2/docs/api-v2-conventions-and-shared-behaviors).