POST | Criar grupo de usuários

Descrição

Crie um grupo de usuários na plataforma. A requisição define o nome do grupo e uma descrição opcional. O grupo é criado no estado ativo, sem membros e sem vínculos com políticas de acesso.

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

POST /api/v2/iam/user-groups

Cabeçalhos

Cabeçalho	Obrigatório	Descrição
`Content-Type`	Sim	Deve ser `application/json`.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do grupo de usuários. Limitado a 100 caracteres. O nome deve ser único entre todos os grupos de usuários, incluindo os excluídos e desativados.
`description`	string	Não	Descrição do grupo de usuários. Limitada a 512 caracteres. Retorna `null` quando não informada.

Info

O estado active não pode ser definido aqui. Um grupo é ativado e desativado por meio de POST | Ativar grupo de usuários e POST | Desativar grupo de usuários. O campo external_id também não pode ser definido, ele é atribuído pela sincronização LDAP. Enviar id, active, external_id, tenant_code, created_at ou updated_at retorna 422.

Exemplo de requisição

POST {{url}}/api/v2/iam/user-groups

Corpo

{
  "name": "Payments",
  "description": "Finance team group"
}

Resposta

HTTP/1.1 201 Created
Location: /api/v2/iam/user-groups/7
ETag: "v1"
X-Request-Id: 7f3c1a90-2c4e-4b1a-9f5e-0a2b7c9d1e34

O cabeçalho Location carrega o caminho do grupo criado e corresponde a meta.links.self.

Info

O cabeçalho ETag carrega a entity tag do grupo criado. Envie-a no cabeçalho If-Match de PUT | Atualizar grupo de usuários e PATCH | Atualizar parcialmente grupo de usuários sem uma nova requisição GET.

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-01T12:00:00+00:00"
    }
  },
  "meta": {
    "links": {
      "self": "/api/v2/iam/user-groups/7"
    },
    "actions": {
      "deactivate": "/api/v2/iam/user-groups/7/deactivate",
      "users.list": "/api/v2/iam/user-groups/7/users",
      "access-policies.list": "/api/v2/iam/user-groups/7/access-policies"
    }
  }
}

Campos do corpo de resposta

Campo	Tipo	Descrição
`data`	object	O grupo de usuários criado.
`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. Um grupo é criado como 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` para um grupo criado pela API.
`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`	object	Links de navegação do recurso criado.
`meta.links.self`	string	Caminho do grupo de usuários criado.
`meta.actions`	object	Ações disponíveis para o grupo em seu estado atual.

Erros

Código HTTP	Mensagem	Possível causa	Solução
`400`	`api.request.bad_request`	O corpo da requisição não é um JSON válido.	Verifique a sintaxe do corpo 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.validation.required_field`	O campo `name` está ausente ou vazio.	Adicione o campo e reenvie a requisição.
`422`	`api.validation.unique`	Já existe um grupo de usuários com esse nome. Grupos excluídos e desativados mantêm seus nomes.	Escolha um nome diferente.
`422`	`api.validation.length_exceeded`	O `name` excede 100 caracteres ou a `description` excede 512 caracteres.	Reduza o valor e reenvie a requisição.
`422`	`api.validation.invalid_type`	Um campo foi enviado com o tipo de dado incorreto.	Verifique os tipos de campo descritos em Corpo da requisição.
`422`	`api.validation.unknown_field`	O corpo contém um campo fora do conjunto permitido.	Envie apenas `name` e `description`.
`422`	`patch.field.not.allowed`	O corpo contém um campo gerenciado pela plataforma, como `active` ou `external_id`.	Remova o campo. Envie apenas `name` e `description`.
`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.