GET | Listar todos os membros de um grupo de usuários

Descrição

Liste os membros ativos de um grupo de usuários. A resposta é paginada, e cada linha informa como o vínculo foi criado, quem o adicionou e quando.

O campo creation_type é o que separa um vínculo gerenciado por uma integração de um gerenciado por um diretório. Um grupo cujos vínculos vêm de uma sincronização não pode ser editado pela API.

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}/users

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.

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`, limitado ao máximo de `200` definido para toda a plataforma.

Exemplo de requisição

GET {{url}}/api/v2/iam/user-groups/7/users?page=1&limit=50

Resposta

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

Exemplo de corpo de resposta

{
  "data": [
    {
      "id": "10",
      "name": "Alice Doe",
      "username": "alice",
      "email": "[email protected]",
      "creation_type": "local",
      "added_by": "admin",
      "added_at": "2026-04-15T09:30:00+00:00"
    },
    {
      "id": "11",
      "name": "Bob Doe",
      "username": "bob",
      "email": "[email protected]",
      "creation_type": "synced",
      "added_by": null,
      "added_at": "2026-04-12T08:00:00+00:00"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 50,
      "total_items": 2,
      "total_pages": 1
    },
    "links": {
      "self": "/api/v2/iam/user-groups/7/users?page=1&limit=50"
    }
  }
}

Campos do corpo de resposta

Campo	Tipo	Descrição
`data`	array[object]	Membros ativos na página atual.
`data[].id`	string	Código de identificação único do usuário.
`data[].name`	string	Nome completo do usuário.
`data[].username`	string	Nome de usuário.
`data[].email`	string	Endereço de e-mail do usuário. Retorna `null` quando o usuário não tem endereço cadastrado.
`data[].creation_type`	string	Como o vínculo foi criado. Retorna `local` quando foi adicionado pela API ou pela interface web, e `synced` quando uma sincronização LDAP o provisionou.
`data[].added_by`	string	Nome de exibição do usuário que adicionou o vínculo. Retorna `null` para um vínculo criado por sincronização.
`data[].added_at`	datetime	Data e hora de criação do vínculo.
`meta`	object	Metadados da listagem.
`meta.pagination`	object	Estado da paginação para a requisição atual.
`meta.links.self`	string	Caminho da página atual.

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.
`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.