# Create a group (/docs/apis/management/groups/CreateGroup)

`POST /groups`

Creates a new group that can be referenced in access policies, role assignments or user membership management. Creation of more than two groups requires an active Pro plan subscription.

Base URL: `https://{tenant}.{region}.monocloud.com/api`, where `{tenant}`, `{region}` (one of us, eu, in) come from your tenant. Authentication: send your Management API key in the `X-API-KEY` header.

## Request body

JSON, required. The request payload used to create a group.

- `name` (string, required) The display name of the group.
- `description` (string) Description that explains the purpose or role of the group.
- `is_auto_assigned` (boolean, default false) Indicates whether users are automatically added to this group upon sign-up.

## Response body

`201`, JSON. Group was created successfully

Returns `Group`.

- `group_id` (string, required, uuid) The unique identifier of the group.
- `type` (string, required) Specifies whether the group is system-defined or user-managed. One of: `built_in`, `custom`.
- `name` (string, required) The display name of the group.
- `description` (string) Description that explains the purpose or role of the group.
- `is_auto_assigned` (boolean, required) Indicates whether users are automatically added to this group upon sign-up.
- `users_assigned` (integer, required, int64) The number of users currently assigned to the group.
- `clients_assigned` (integer, required, int64) The number of client applications associated with the group.
- `creation_time` (integer, required, date-time) Specifies the time at which the group was created (in Epoch).
- `last_updated` (integer, required, date-time) Specifies the time at which the group was last updated (in Epoch).
- `last_assigned` (integer, required, date-time) Specifies the time of the most recent user or client assignment to the group (in Epoch).

## Errors

- `400` Bad Request
  - `type` (string, required) A URI reference that identifies the error type. When accessed, it may provide human-readable documentation.
  - `title` (string, required) A short, human-readable summary of the error.
  - `status` (integer, required, int32) The HTTP status code associated with this error response.
  - `trace_id` (string, required) A unique identifier for the request, used for tracing and diagnostics.
  - `detail` (string) A human-readable explanation specific to this occurrence of the error.
  - `instance` (string) A URI reference that identifies the specific occurrence of the error.
- `401` Unauthorized
- `402` Payment Required
  Same body as `400`.
- `403` Forbidden
- `409` Conflict
  Same body as `400`.
- `422` Unprocessable Entity
  - `KeyValidationProblemDetails`
    - `type` (string, required) A URI reference that identifies the error type. When accessed, it may provide human-readable documentation.
    - `title` (string, required) A short, human-readable summary of the error.
    - `status` (integer, required, int32) The HTTP status code associated with this error response.
    - `trace_id` (string, required) A unique identifier for the request, used for tracing and diagnostics.
    - `detail` (string) A human-readable explanation specific to this occurrence of the error.
    - `instance` (string) A URI reference that identifies the specific occurrence of the error.
    - `errors` (Record<string, string[]>, required) A key-value map of validation errors, where each key represents a request field and the value contains one or more messages describing why the request could not be processed.
  - `IdentityValidationProblemDetails`
    - `type` (string, required) A URI reference that identifies the error type. When accessed, it may provide human-readable documentation.
    - `title` (string, required) A short, human-readable summary of the error.
    - `status` (integer, required, int32) The HTTP status code associated with this error response.
    - `trace_id` (string, required) A unique identifier for the request, used for tracing and diagnostics.
    - `detail` (string) A human-readable explanation specific to this occurrence of the error.
    - `instance` (string) A URI reference that identifies the specific occurrence of the error.
    - `errors` (IdentityError[], required) List of identity validation errors describing why the request could not be processed.

## Example (MonoCloud .NET SDK)

```csharp
using MonoCloud.Management;
using MonoCloud.Management.Models;
using MonoCloud.Management.Core.Base;

var apiClient = new MonoCloudManagementClient(new MonoCloudConfig("<your-domain>", "[[API-Key]]"));


var requestBody = new CreateGroupRequest
  {
    Name = "Administrators",
    Description = "The administrator group",
    IsAutoAssigned = false,
  };


var result = await apiClient.Groups.CreateGroupAsync(requestBody);
```

## Example (MonoCloud Javascript SDK)

```javascript
import { MonoCloudManagementClient } from '@monocloud/management';

const apiClient = MonoCloudManagementClient.init({ domain: '<your-domain>', apiKey: '[[API-Key]]' });

const requestBody = {
  name: 'Administrators',
  description: 'The administrator group',
  is_auto_assigned: false
};

const result = apiClient.groups.createGroup(requestBody);
```