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: the group becomes inactive and all of its memberships are removed. After the deletion:

GET | List a user group returns 200 with active: false.
The group still appears in GET | List all user groups unless you filter with user_group.active=true.
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.
A valid OAuth 2.0 access token. For more information, access 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.
`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.