Description
Remove one or more users from a user group. The memberships are deactivated rather than erased, and a user who is not currently a member is ignored, so the same request can be repeated safely.
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.
- The group must not be managed by an active LDAP synchronization.
Request
POST /api/v2/iam/user-groups/{id}/users/remove
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
integer | Yes | Unique identification code of the user group. |
Headers
| Header | Required | Description |
|---|---|---|
Content-Type |
Yes | Must be application/json. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
user_ids |
array[integer] | Yes | Identification codes of the users to remove. The array must hold at least one value. Numeric strings, such as "11", are also accepted. |
Example request
POST {{url}}/api/v2/iam/user-groups/7/users/remove
Body
{
"user_ids": [11]
}
Response
HTTP/1.1 204 No Content
X-Request-Id: 7f3c1a90-2c4e-4b1a-9f5e-0a2b7c9d1e34
The removal is applied when the response arrives. A successful request returns no body.
Depending on the access-control configuration of the platform, the resulting changes to the effective access of the affected users can be applied in the background shortly after the response. For offboarding, where the revocation is the point of the request, account for this short delay.
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.inactive |
The user group is inactive. | Activate the group, then retry. For more information, access POST | Activate user group. |
422 |
api.validation.required_field |
The body does not carry user_ids. |
Add the field and resend the request. |
422 |
api.validation.invalid_reference |
One of the identification codes in user_ids does not match an existing user. |
Check the codes and resend the request. |
422 |
api.validation.invalid_type |
A value in user_ids is not an integer or a numeric string. |
Send integers or numeric strings only. |
422 |
user_group.users.locked_by_ldap_sync |
The membership of the group is managed by an active LDAP synchronization. | Change the membership at the directory source, or remove the group from the synchronization scope. |
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.