---
title: "Create a realm"
method: POST
path: "/clusters/{cluster_id}/realms"
tags: ["Realms"]
---

# Create a realm

`POST /clusters/{cluster_id}/realms`

## Request

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

Creates a new realm in the specified cluster. The cluster must be in the `available` state.

Required scope: `realms:write`

## Path parameters

- `cluster_id` string, uuid, required

## Headers

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

## Request body

- CreateRealmRequest: Request body for creating a realm. If `display_name` is omitted, the realm name is used.
  - `name` string, required: Keycloak realm name (not ID). Must start with a letter; allows letters, digits, and hyphens.
  - `display_name` string
  - `apply_default_branding` boolean: Whether to apply Skycloak's default login branding to the new realm. Defaults to `true` when omitted, so the realm serves the Skycloak look instead of the stock Keycloak login page. Set to `false` to leave the realm's themes untouched. Branding can always be applied or reset later from the realm's Branding page.

## Response `201`

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

- CreatedRealm: Realm details returned when a realm is created.
  - `id` string, uuid, required: Keycloak realm ID. This is a UUID generated by Keycloak.
  - `name` string, required: Keycloak realm name (not ID). Must start with a letter; allows letters, digits, and hyphens.
  - `display_name` string, required
  - `enabled` boolean, required: Whether users can sign in to this realm.
  - `ssl_required` 'external' | 'all' | 'none', required: Keycloak SSL requirement. Maps directly to Keycloak's `sslRequired` realm setting.
  - `registration_allowed` boolean, required: Whether self-registration is open to anyone.
  - `registration_email_as_username` boolean, required: Whether email addresses are used as usernames during registration.
  - `login_with_email_allowed` boolean, required: Whether users can sign in with their email address instead of username.
  - `duplicate_emails_allowed` boolean, required: Whether multiple accounts may share the same email address.
  - `created_at` string, date-time: Time when the realm was created, when available.
  - `default_branding_applied` boolean: Whether Skycloak's default login branding was applied to the realm as part of this create. `false` when `apply_default_branding` was set to `false`, and also when the branding step failed: the realm is created either way, and branding can be applied from the realm's Branding page.

## 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)