---
title: "DELETE | Delete user group by [id]"
slug: "api-v2-delete-user-group"
updated: 2026-09-29T16:15:22Z
published: 2026-09-29T16:15:22Z
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 | Delete user group by [id]

## Description

Delete a user group. The platform applies a soft delete, so the record is deactivated rather than erased, and all memberships of the group are removed with it. Membership alone never blocks the deletion.

The deletion is refused while the group is still in use elsewhere. Four references block it, and the response names which one applies.

This request does not use the `If-Match` header.

              Attention

              

Deleting a group has the same effect as [POST | Deactivate user group](/v4-2/docs/api-v2-post-deactivate-user-group): the group becomes inactive and all of its memberships are removed. After the deletion:

- [GET | List a user group](/v4-2/docs/api-v2-get-list-a-user-group) returns `200` with `active: false`.
- The group still appears in [GET | List all user groups](/v4-2/docs/api-v2-get-list-all-user-groups) unless you filter with `user_group.active=true`.
- [POST | Activate user group](/v4-2/docs/api-v2-post-activate-user-group) restores the group, but not its members.
- The name stays reserved. Creating a group with the same name returns `422` `api.validation.unique`.
- A new `DELETE` request on the same group returns `204` again.

---

## Prerequisites

- An application with the **Users** authorization granted by the administrator in A2A. For more information, access [How to manage authorizations in A2A](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a).
- A valid OAuth 2.0 access token. For more information, access [How to authenticate an application in A2A](/v4-2/docs/how-to-authenticate-an-application-in-a2a).

---

## Request

`DELETE` `/api/v2/iam/user-groups/{id}`

### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Yes | Unique identification code of the user group. |

### Example request

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

---

## Response

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

A successful deletion returns no body.

---

## Blockers

When the group is still referenced, the platform returns `409` with the code `api.resource.in_use`, and the `details` array names the reference.

Each response names one reference only. The platform checks the references in the order of the following table and stops at the first one it finds. After you clear a reference, a new request can return the next one.

| Code in `details[].code` | Meaning | Solution |
| --- | --- | --- |
| `user_group.in_use.access_policies` | The group still has active access policy bindings. | Remove the bindings, access [POST \| Remove access policies from a user group](/v4-2/docs/api-v2-remove-user-group-access-policies). |
| `user_group.in_use.ldap_sync` | The group is linked to an active LDAP synchronization. | Remove the group from the synchronization scope, then retry. |
| `user_group.in_use.review` | A member of the group has a user review that is pending or in progress. | Conclude the review, then retry. |
| `user_group.in_use.certification_owners` | The group has active certification campaign owners. | Remove the owners or conclude the campaign, then retry. |

### Example error response

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

---

## Errors

| HTTP code | Message | Possible cause | Solution |
| --- | --- | --- | --- |
| `401` | `api.auth.unauthorized` | The access token is missing, invalid, or has expired. | Request a new access token. |
| `404` | `api.resource.not_found` | The user group does not exist, or it is outside the scope of the authorization. | Check the identification code and the authorization scope. |
| `409` | `api.resource.in_use` | The group is still referenced. | Check the code returned in `details` and clear the reference. See **Blockers**. |
| `429` | `api.rate_limit_exceeded` | The request rate limit was exceeded. | Wait the number of seconds returned in the `Retry-After` header and try again. |

For authentication error messages and the `403` versus `404` policy, access [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors).