---
title: "PUT | Update user group by [id]"
slug: "api-v2-put-update-user-group"
updated: 2026-11-03T14:57:57Z
published: 2026-11-03T14:57:57Z
canonical: "docs.senhasegura.io/api-v2-put-update-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.

# PUT | Update user group by [id]

## Description

Replace the editable attributes of a user group. The request body carries the complete set of editable fields, so any optional field omitted from the body is cleared.

The request requires the `If-Match` header, which protects the group against concurrent changes. To change only some fields, access [PATCH | Partially update user group](/v4-2/docs/api-v2-patch-update-user-group).

---

## 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 current entity tag of the group, returned in the `ETag` header by [GET | List a user group](/v4-2/docs/api-v2-get-list-a-user-group).
- The group must be active. An inactive group is refused, access [POST | Activate user group](/v4-2/docs/api-v2-post-activate-user-group) first.

---

## Request

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

### 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`. |
| `If-Match` | Yes | Entity tag of the group, as returned by the most recent `GET` request. The platform returns `412` when the value is stale and `428` when the header is absent. |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Name of the user group. Limited to 100 characters and must be unique across the platform. |
| `description` | string | No | Description of the user group. Limited to 512 characters. Omitting the field clears the current value. |

              Attention

              

The fields `id`, `active`, `external_id`, `tenant_code`, `created_at`, and `updated_at` are rejected with `patch.field.not.allowed`. State changes go through the activate and deactivate actions, and `external_id` is managed by the LDAP synchronization.

---

### Example request

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

#### Body

```
{
  "name": "Payments - Administrators",
  "description": "Finance team group, administrator scope."
}
```

---

## Response

```
HTTP/1.1 200 OK
ETag: "v2"
X-Request-Id: 7f3c1a90-2c4e-4b1a-9f5e-0a2b7c9d1e34
```

The `ETag` header holds the new entity tag. Use this value in the `If-Match` header of the next update or deletion.

### Example response body

```
{
  "data": {
    "id": "7",
    "user_group": {
      "name": "Payments - Administrators",
      "active": true,
      "description": "Finance team group, administrator scope.",
      "external_id": null,
      "created_at": "2026-04-01T12:00:00+00:00",
      "updated_at": "2026-04-16T11:05:00+00:00"
    }
  },
  "meta": {
    "links": {
      "self": "/api/v2/iam/user-groups/7"
    },
    "actions": {
      "deactivate": "/api/v2/iam/user-groups/7/deactivate"
    }
  }
}
```

---

## Response body fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | object | The updated user group. |
| `data.id` | string | Unique identification code of the user group, assigned by Segura™. |
| `data.user_group` | object | Attributes of the user group. |
| `data.user_group.name` | string | Name of the user group. |
| `data.user_group.active` | boolean | Indicates whether the user group is active. |
| `data.user_group.description` | string | Description of the user group. Returns `null` when cleared. |
| `data.user_group.external_id` | string | External identifier of the group in the LDAP or Active Directory source. |
| `data.user_group.created_at` | datetime | Date and time when the user group was created. |
| `data.user_group.updated_at` | datetime | Date and time of this change. |
| `meta` | object | Resource metadata. |
| `meta.links.self` | string | Path of the user group. |
| `meta.actions` | object | Actions available for the group in its current state. |

---

## Errors

| HTTP code | Message | Possible cause | Solution |
| --- | --- | --- | --- |
| `400` | `api.request.bad_request` | The request body is not valid JSON. | Check the body syntax and resend the request. |
| `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 and retry. |
| `412` | `api.precondition.failed` | The `If-Match` value does not match the current entity tag, so another change was applied first. | Send a new `GET` request, take the fresh entity tag, and retry. |
| `422` | `api.validation.required_field` | The `name` field is missing or empty. | Add the field and resend the request. |
| `422` | `api.validation.unique` | Another user group already uses this name. | Choose a different name. |
| `422` | `api.validation.length_exceeded` | The `name` exceeds 100 characters or the `description` exceeds 512 characters. | Shorten the value and resend the request. |
| `422` | `patch.field.not.allowed` | The body contains `id`, `active`, `external_id`, `tenant_code`, `created_at`, or `updated_at`. | Send only `name` and `description`. |
| `422` | `api.validation.unknown_field` | The body contains a field that the user group does not have. | Send only `name` and `description`. |
| `428` | `api.precondition.required` | The `If-Match` header was not sent. | Send a new `GET` request, take the entity tag, and retry with the header. |
| `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).