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

# PATCH | Partially update user group by [id]

## Description

Change selected attributes of a user group. The request body follows the JSON Merge Patch format and lists only the fields to change, so every field left out keeps its current value.

The request requires the `If-Match` header, which protects the group against concurrent changes. To replace the whole resource, access [PUT | Update user group](/v4-2/docs/api-v2-put-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

`PATCH` `/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/merge-patch+json`. The platform returns `415` for any other media type, including `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 | No | New name of the user group. Limited to 100 characters and must be unique across the platform. |
| `description` | string | No | New description of the user group. Limited to 512 characters. |

              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, so sending it would break the link to the external group.

---

### Example request

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

#### Headers

```
Content-Type: application/merge-patch+json
If-Match: "v2"
```

#### Body

```
{
  "description": "Finance team group, reviewed in April."
}
```

---

## Response

```
HTTP/1.1 200 OK
ETag: "v3"
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, reviewed in April.",
      "external_id": null,
      "created_at": "2026-04-01T12:00:00+00:00",
      "updated_at": "2026-04-18T08:20: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, including the fields left unchanged. |
| `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. |
| `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. |
| `415` | `api.request.unsupported_media_type` | The `Content-Type` header is not `application/merge-patch+json`. | Send the header with `application/merge-patch+json` and retry. |
| `422` | `patch.field.not.allowed` | The body contains `id`, `active`, `external_id`, `tenant_code`, `created_at`, or `updated_at`. | Send only `name` or `description`. |
| `422` | `api.validation.unknown_field` | The body contains a field that the user group does not have. | Send only `name` or `description`. |
| `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. |
| `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).