---
title: "PUT | Atualizar grupo de usuários"
slug: "api-v2-put-update-user-group"
updated: 2026-11-03T14:57:57Z
published: 2026-11-03T14:57:57Z
canonical: "docs.senhasegura.io/api-v2-put-update-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.

# 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](/v4-2/docs/api-v2-patch-update-user-group).

---

## 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).
- A entity tag atual do grupo, retornada no cabeçalho `ETag` por [GET | Consultar um grupo de usuários](/v4-2/docs/api-v2-get-list-a-user-group).
- O grupo deve estar ativo. Um grupo inativo é recusado, acesse [POST | Ativar grupo de usuários](/v4-2/docs/api-v2-post-activate-user-group) 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](/v4-2/docs/api-v2-conventions-and-shared-behaviors).