--- title: "POST | Criar grupo de usuários" slug: "api-v2-post-create-user-group" updated: 2026-11-03T14:57:58Z published: 2026-11-03T14:57:58Z canonical: "docs.senhasegura.io/api-v2-post-create-user-group" --- > ## 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. # 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](/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 `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](/v4-2/docs/api-v2-post-activate-user-group) e [POST | Desativar grupo de usuários](/v4-2/docs/api-v2-post-deactivate-user-group). 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](/v4-2/docs/api-v2-put-update-user-group) e [PATCH | Atualizar parcialmente grupo de usuários](/v4-2/docs/api-v2-patch-update-user-group) 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](/v4-2/docs/api-v2-conventions-and-shared-behaviors).