---
title: "Create a realm group"
method: POST
path: "/clusters/{cluster_id}/realms/{realm_name}/groups"
tags: ["Realm Groups"]
---

# Create a realm group

`POST /clusters/{cluster_id}/realms/{realm_name}/groups`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/clusters/{cluster_id}/realms/{realm_name}/groups`
- Auth: API key in header `API-Key`

Creates a new group. Omit `parent_id` to create a top-level group.

Required scope: `realm-groups:write`

## Path parameters

- `cluster_id` string, uuid, required
- `realm_name` string, required: Keycloak realm name (not ID). Must start with a letter; allows letters, digits, and hyphens.

## Headers

- `API-Version` '2026-06-01.beta', required

## Request body

- CreateRealmGroupRequest: Request body for creating a realm group. Omit `parent_id` to create a top-level group.
  - `name` string, required: Group name (leaf segment of the path).
  - `parent_id` string, uuid

## Response `201`

The request has succeeded and a new resource has been created as a result.

- RealmGroup
  - `id` string, uuid, required
  - `name` string, required
  - `path` string, required: Canonical realm group path.
  - `sub_group_count` integer: Number of direct child groups.
  - `subgroups` RealmSubGroup[]: Direct child groups. Only populated when `include_subgroups=true` is passed to the list endpoint.
    - `id` string, uuid, required
    - `name` string, required
    - `path` string, required: Canonical realm group path.
    - `sub_group_count` integer: Number of direct child groups.

## Other responses

- `401`: Access is unauthorized.
- `403`: Access is forbidden.
- `404`: The server cannot find the requested resource.
- `409`: The request conflicts with the current state of the server.
- `422`: Client error
- `429`: Client error
- `500`: Server error
- `501`: Server error

---

[API](https://skmtc.dev/skycloak/apis/skycloak-public-api.md) · [All operations](https://skmtc.dev/skycloak/apis/skycloak-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skycloak/apis/skycloak-public-api/revisions/33a69e2ce35f?raw)