---
title: "POST | Create user group"
slug: "api-v2-post-create-user-group"
updated: 2026-11-03T14:57:58Z
published: 2026-11-03T14:57:58Z
canonical: "docs.senhasegura.io/api-v2-post-create-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.

# 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](/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).

              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](/v4-2/docs/api-v2-post-activate-user-group) and [POST | Deactivate user group](/v4-2/docs/api-v2-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](/v4-2/docs/api-v2-put-update-user-group) and [PATCH | Partially update user group](/v4-2/docs/api-v2-patch-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](/v4-2/docs/api-v2-conventions-and-shared-behaviors).