GET | List a user group by [id]

Description

Retrieve the full detail of a single user group by its identification code. The response carries the group attributes, the actions available in its current state, and a strong entity tag in the ETag header.

Send this request before any update, the ETag value is what PUT | Update user group and PATCH | Partially update user group require in the If-Match header.

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.

Request

GET /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
`If-None-Match`	No	Entity tag from a previous response, used for cache validation. When the value matches the current entity tag, the server returns `304 Not Modified` with no body.

Query parameters

Parameter	Type	Description
`fields`	string	Comma-separated list of keys to return. Allowed values: `id`, `user_group`, `user_group.name`, `user_group.active`, `user_group.description`, `user_group.external_id`, `user_group.created_at`, `user_group.updated_at`.

Example request

GET {{url}}/api/v2/iam/user-groups/7

Response

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

Example response body

{
  "data": {
    "id": "7",
    "user_group": {
      "name": "Payments",
      "active": true,
      "description": "Finance team group",
      "external_id": null,
      "created_at": "2026-04-01T12:00:00+00:00",
      "updated_at": "2026-04-15T09:30:00+00:00"
    }
  },
  "meta": {
    "links": {
      "self": "/api/v2/iam/user-groups/7"
    },
    "actions": {
      "users.list": "/api/v2/iam/user-groups/7/users",
      "access-policies.list": "/api/v2/iam/user-groups/7/access-policies",
      "deactivate": "/api/v2/iam/user-groups/7/deactivate"
    }
  }
}

Response body fields

Field	Type	Description
`data`	object	The requested 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 not provided.
`data.user_group.external_id`	string	External identifier of the group in the LDAP or Active Directory source. Returns `null` when the group is not linked to an external group.
`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 the last change to the user group.
`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. An active group offers `deactivate`, an inactive group offers `activate`.
`meta.actions.users.list`	string	Path used to list the members of the group.
`meta.actions.access-policies.list`	string	Path used to list the access policy bindings of the group.

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.
`422`	`api.validation.invalid_field`	The `fields` parameter references a key that is not part of the schema.	Use only the allowed values listed in Query parameters.
`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.

Info

A 404 response also covers groups that exist but are outside the caller's tenant or authorization scope. For the full 403 versus 404 policy, access API v2 - Conventions and shared behaviors.