PUT | Atualizar grupo de usuários

Descrição

Substitua os atributos editáveis de um grupo de usuários. O corpo da requisição carrega o conjunto completo de campos editáveis, então qualquer campo opcional omitido do corpo é apagado.

A requisição exige o cabeçalho If-Match, que protege o grupo contra alterações concorrentes. Para alterar apenas alguns campos, acesse PATCH | Atualizar parcialmente grupo de usuários.

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.
A entity tag atual do grupo, retornada no cabeçalho ETag por GET | Consultar um grupo de usuários.
O grupo deve estar ativo. Um grupo inativo é recusado, acesse POST | Ativar grupo de usuários antes.

Requisição

PUT /api/v2/iam/user-groups/{id}

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.

Cabeçalhos

Cabeçalho	Obrigatório	Descrição
`Content-Type`	Sim	Deve ser `application/json`.
`If-Match`	Sim	Entity tag do grupo, conforme retornada pela requisição `GET` mais recente. A plataforma retorna `412` quando o valor está desatualizado e `428` quando o cabeçalho está ausente.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do grupo de usuários. Limitado a 100 caracteres e deve ser único em toda a plataforma.
`description`	string	Não	Descrição do grupo de usuários. Limitada a 512 caracteres. Omitir o campo apaga o valor atual.

Atenção

Os campos id, active, external_id, tenant_code, created_at e updated_at são rejeitados com patch.field.not.allowed. Mudanças de estado passam pelas ações de ativação e desativação, e o external_id é gerenciado pela sincronização LDAP.

Exemplo de requisição

PUT {{url}}/api/v2/iam/user-groups/7

Corpo

{
  "name": "Payments - Administrators",
  "description": "Finance team group, administrator scope."
}

Resposta

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

O cabeçalho ETag carrega a nova entity tag. Use esse valor no cabeçalho If-Match da próxima atualização ou exclusão.

Exemplo de corpo de resposta

{
  "data": {
    "id": "7",
    "user_group": {
      "name": "Payments - Administrators",
      "active": true,
      "description": "Finance team group, administrator scope.",
      "external_id": null,
      "created_at": "2026-04-01T12:00:00+00:00",
      "updated_at": "2026-04-16T11:05:00+00:00"
    }
  },
  "meta": {
    "links": {
      "self": "/api/v2/iam/user-groups/7"
    },
    "actions": {
      "deactivate": "/api/v2/iam/user-groups/7/deactivate"
    }
  }
}

Campos do corpo de resposta

Campo	Tipo	Descrição
`data`	object	O grupo de usuários atualizado.
`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.description`	string	Descrição do grupo de usuários. Retorna `null` quando apagada.
`data.user_group.external_id`	string	Identificador externo do grupo na origem LDAP ou Active Directory.
`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 desta alteração.
`meta`	object	Metadados do recurso.
`meta.links.self`	string	Caminho do grupo de usuários.
`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.
`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.
`409`	`api.resource.inactive`	O grupo de usuários está inativo.	Ative o grupo e tente novamente.
`412`	`api.precondition.failed`	O valor de `If-Match` não corresponde à entity tag atual, então outra alteração foi aplicada antes.	Envie uma nova requisição `GET`, obtenha a entity tag atualizada e tente novamente.
`422`	`api.validation.required_field`	O campo `name` está ausente ou vazio.	Adicione o campo e reenvie a requisição.
`422`	`api.validation.unique`	Outro grupo de usuários já usa esse nome.	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`	`patch.field.not.allowed`	O corpo contém `id`, `active`, `external_id`, `tenant_code`, `created_at` ou `updated_at`.	Envie apenas `name` e `description`.
`422`	`api.validation.unknown_field`	O corpo contém um campo que o grupo de usuários não tem.	Envie apenas `name` e `description`.
`428`	`api.precondition.required`	O cabeçalho `If-Match` não foi enviado.	Envie uma nova requisição `GET`, obtenha a entity tag e tente novamente com o cabeçalho.
`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.