---
title: "DELETE | Excluir grupo de usuários"
slug: "api-v2-delete-user-group"
updated: 2026-09-29T16:24:38Z
published: 2026-09-29T16:24:38Z
canonical: "docs.senhasegura.io/api-v2-delete-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.

# DELETE | Excluir grupo de usuários

## Descrição

Exclua um grupo de usuários. A plataforma aplica uma exclusão lógica, então o registro é desativado em vez de apagado, e todos os vínculos de membro do grupo são removidos junto com ele. O vínculo de membro isoladamente nunca bloqueia a exclusão.

A exclusão é recusada enquanto o grupo ainda está em uso em outro lugar. Quatro referências bloqueiam a exclusão, e a resposta identifica qual delas se aplica.

Esta requisição não usa o cabeçalho `If-Match`.

              Atenção

              

Excluir um grupo tem o mesmo efeito que [POST | Desativar grupo de usuários](/v4-2/docs/api-v2-post-deactivate-user-group): o grupo fica inativo e todos os seus vínculos de membro são removidos. Após a exclusão:

- [GET | Consultar um grupo de usuários](/v4-2/docs/api-v2-get-list-a-user-group) retorna `200` com `active: false`.
- O grupo continua aparecendo em [GET | Listar todos os grupos de usuários](/v4-2/docs/api-v2-get-list-all-user-groups), a menos que você filtre com `user_group.active=true`.
- [POST | Ativar grupo de usuários](/v4-2/docs/api-v2-post-activate-user-group) restaura o grupo, mas não os seus membros.
- O nome continua reservado. Criar um grupo com o mesmo nome retorna `422` `api.validation.unique`.
- Uma nova requisição `DELETE` no mesmo grupo retorna `204` novamente.

---

## 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).

---

## Requisição

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

### Exemplo de requisição

`DELETE` `{{url}}/api/v2/iam/user-groups/7`

---

## Resposta

```
HTTP/1.1 204 No Content
X-Request-Id: 7f3c1a90-2c4e-4b1a-9f5e-0a2b7c9d1e34
```

Uma exclusão bem-sucedida não retorna corpo.

---

## Bloqueios

Quando o grupo ainda é referenciado, a plataforma retorna `409` com o código `api.resource.in_use`, e o array `details` identifica a referência.

Cada resposta identifica uma única referência. A plataforma verifica as referências na ordem da tabela a seguir e para na primeira que encontra. Depois que você elimina uma referência, uma nova requisição pode retornar a próxima.

| Código em `details[].code` | Significado | Solução |
| --- | --- | --- |
| `user_group.in_use.access_policies` | O grupo ainda tem vínculos ativos com políticas de acesso. | Remova os vínculos, acesse [POST \| Remover políticas de acesso de um grupo de usuários](/v4-2/docs/api-v2-remove-user-group-access-policies). |
| `user_group.in_use.ldap_sync` | O grupo está vinculado a uma sincronização LDAP ativa. | Remova o grupo do escopo da sincronização e tente novamente. |
| `user_group.in_use.review` | Um membro do grupo tem uma revisão de usuário pendente ou em andamento. | Conclua a revisão e tente novamente. |
| `user_group.in_use.certification_owners` | O grupo tem proprietários de campanha de certificação ativos. | Remova os proprietários ou conclua a campanha e tente novamente. |

### Exemplo de resposta de erro

```
{
  "code": "api.resource.in_use",
  "message": "User group is in use by active access-policy bindings.",
  "details": [
    {
      "code": "user_group.in_use.access_policies"
    }
  ]
}
```

---

## 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. |
| `409` | `api.resource.in_use` | O grupo ainda é referenciado. | Verifique o código retornado em `details` e elimine a referência. Veja **Bloqueios**. |
| `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).