Description
Add one or more users to a user group. A user who is already an active member is ignored, and a membership that exists but is inactive is reactivated, 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 users referenced in
user_idsmust already exist on the platform. - The group must not be managed by an active LDAP synchronization.
Request
POST /api/v2/iam/user-groups/{id}/users
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 add. The array must hold at least one value. Numeric strings, such as "10", are also accepted. |
Example request
POST {{url}}/api/v2/iam/user-groups/7/users
Body
{
"user_ids": [10, 11]
}
Response
HTTP/1.1 204 No Content
X-Request-Id: 7f3c1a90-2c4e-4b1a-9f5e-0a2b7c9d1e34
The membership change is applied when the response arrives. A successful request returns no body.
Info
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.
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.