POST | Create user group

Description

Create a user group on the platform. The request defines the group name and an optional description. The group is created in the active state, with no members and no access policy bindings.

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.

Info

An access token carries only the authorizations that existed when it was generated. After the administrator enables the Users authorization, generate a new token for the application, an existing token will not gain the new authorization.

Request

POST /api/v2/iam/user-groups

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`.

Request body

Field	Type	Required	Description
`name`	string	Yes	Name of the user group. Limited to 100 characters. The name must be unique across all user groups, including deleted and deactivated ones.
`description`	string	No	Description of the user group. Limited to 512 characters. Returns `null` when not provided.

Info

The active state cannot be set here. A group is activated and deactivated through POST | Activate user group and POST | Deactivate user group. The external_id field cannot be set either, it is assigned by the LDAP synchronization. Sending id, active, external_id, tenant_code, created_at, or updated_at returns 422.

Example request

POST {{url}}/api/v2/iam/user-groups

Body

{
  "name": "Payments",
  "description": "Finance team group"
}

Response

HTTP/1.1 201 Created
Location: /api/v2/iam/user-groups/7
ETag: "v1"
X-Request-Id: 7f3c1a90-2c4e-4b1a-9f5e-0a2b7c9d1e34

The Location header holds the path of the created group and matches meta.links.self.

Info

The ETag header holds the entity tag of the created group. Send it in the If-Match header of PUT | Update user group and PATCH | Partially update user group without a new GET request.

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-01T12:00:00+00:00"
    }
  },
  "meta": {
    "links": {
      "self": "/api/v2/iam/user-groups/7"
    },
    "actions": {
      "deactivate": "/api/v2/iam/user-groups/7/deactivate",
      "users.list": "/api/v2/iam/user-groups/7/users",
      "access-policies.list": "/api/v2/iam/user-groups/7/access-policies"
    }
  }
}

Response body fields

Field	Type	Description
`data`	object	The created 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. A group is created as 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` for a group created through the API.
`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`	object	Navigation links for the created resource.
`meta.links.self`	string	Path of the created 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.
`422`	`api.validation.required_field`	The `name` field is missing or empty.	Add the field and resend the request.
`422`	`api.validation.unique`	A user group with this name already exists. Deleted and deactivated groups keep their names.	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`	`api.validation.invalid_type`	A field was sent with the wrong data type.	Check the field types described in Request body.
`422`	`api.validation.unknown_field`	The body contains a field outside the allowed set.	Send only `name` and `description`.
`422`	`patch.field.not.allowed`	The body contains a field that the platform manages, such as `active` or `external_id`.	Remove the field. Send only `name` and `description`.
`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.