# Create a Group

A new group of your tenant's users, empty: add its members next.

## Overview

- `name`: 1 to 100 characters once trimmed, unique in your tenant whatever its case (`409` `GROUP_NAME_TAKEN`). `description`: up to 500 characters, or `null`.
- `201` with the group, `memberCount` `0`. Add members with [Add a Member](https://docs.aureahub.com/docs/group-member-add.md).
- For `owner`, `tenantadmin`, `non_signing_admin` and `security_admin`. The body is checked as sent: a field that doesn't belong answers `400` `GROUP_REQUEST_INVALID`.

## Endpoint

### `POST /v1/groups`

Authentication: bearer token required.

Creates an empty group in your tenant.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | 1–100 characters, trimmed; unique in your tenant whatever its case |
| `description` | string \| null | no | Up to 500 characters |

**Responses**

`201` Created

```json
{
  "id": "3b8e1f6a-2c4d-4e9f-a1b7-6d5c4e3f2a10",
  "name": "Finance approvers",
  "description": "Approve transfers above 10,000 EUR",
  "memberCount": 0,
  "createdBy": "5d2c1b0a-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "createdAt": "2026-10-08T09:12:40.118Z",
  "updatedAt": "2026-10-08T09:12:40.118Z"
}
```

`409` Name taken

```json
{
  "statusCode": 409,
  "error": "ConflictError",
  "message": "The tenant has a group by that name",
  "details": { "code": "GROUP_NAME_TAKEN" }
}
```

`400` Invalid

```json
{
  "statusCode": 400,
  "error": "BadRequestError",
  "message": "A group's name is 1 to 100 characters",
  "details": { "code": "GROUP_REQUEST_INVALID" }
}
```

**Example request**

```bash
curl -X POST https://api.aureahub.com/v1/groups \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Finance approvers", "description": "Approve transfers above 10,000 EUR" }'
```

---

Web version: https://docs.aureahub.com/#group-create