---
title: "POST | Add members to a user group by [id]"
slug: "api-v2-post-add-user-group-members"
updated: 2026-09-29T16:15:22Z
published: 2026-09-29T16:15:22Z
canonical: "docs.senhasegura.io/api-v2-post-add-user-group-members"
---

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

# POST | Add members to a user group by [id]

## 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](/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).
- The users referenced in `user_ids` must 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](/v4-2/docs/api-v2-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](/v4-2/docs/api-v2-conventions-and-shared-behaviors).