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.

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

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.