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.

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 current entity tag of the group, returned in the ETag header by GET | List a user group.
The group must be active. An inactive group is refused, access 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.