# Creating a Realm in Keycloak

A <span class="s2">**realm**</span> in Keycloak is the top-level container for managing users, roles, groups, identity providers, and applications. It provides complete logical isolation, making it ideal for multi-tenant systems or staging/production splits. This guide explains different ways to create a realm via the Admin Console, REST API, and Docker CLI while covering permissions, best practices, and troubleshooting.

## **Creating a Realm via Keycloak Admin Console**

The Admin Console is the most straightforward way to create and manage realms using a web-based UI.

#### **Access the Admin Console**

Log in to your Keycloak Admin Console:

```
http://<your-keycloak-domain>/admin/
```

Use the <span class="s1">**admin**</span> account created during setup or one with realm management privileges.

[![image.png](https://docs.elest.io/uploads/images/gallery/2025-06/scaled-1680-/q4uimage.png)](https://docs.elest.io/uploads/images/gallery/2025-06/q4uimage.png)

#### **Create a New Realm**

1. Click the realm dropdown in the top-left corner (default is <span class="s1">master</span>).
2. <span class="s1">Click </span>**Create Realm**<span class="s1">.</span>
3. Enter the following details:
    
    
    - <span class="s1">**Realm Name**</span><span class="s2">: A unique name like </span>customer-portal<span class="s2"> or </span>internal-tools<span class="s2">.</span>
    - <span class="s1">**Display Name**</span>: Optional friendly name shown on login screens.
4. Click <span class="s1">**Create**</span>.

#### **Configure Realm Settings**

Once created, you can adjust behavior by navigating to

- <span class="s1">**Realm Settings &gt; Login**</span>: Enable email verification, OTP, remember-me, etc.
- <span class="s1">**Realm Settings &gt; Themes**</span>: Set custom themes for login and account pages

## **Creating a Realm via Keycloak REST API**

For automation and CI/CD pipelines, use the Admin REST API.

#### **Get Access Token**

Use the master realm or a privileged realm with an admin user.

```bash
curl -X POST "https://<keycloak-domain>/realms/master/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin" \
  -d "password=admin-password" \
  -d "grant_type=password" \
  -d "client_id=admin-cli"
```

Save the <span class="s1">access\_token</span> from the response.

#### **Create the Realm**

```bash
curl -X POST "https://<keycloak-domain>/admin/realms" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "realm": "newrealm",
    "enabled": true,
    "displayName": "New Realm"
  }'
```

This creates a new realm called <span class="s1">newrealm</span> with default settings.

## **Creating a Realm via Docker CLI** 

If Keycloak is running inside a Docker container:

#### **Access the Container**

```
docker exec -it keycloak bash
```

#### **Create Realm Using Import File**

1. Create a JSON realm file (e.g., <span class="s1">myrealm.json</span>):

```yaml
{
  "realm": "myrealm",
  "enabled": true
}
```

2. Run Keycloak with the import flag:

```
kc.sh import --file /opt/keycloak/data/import/myrealm.json
```

Or via Docker:

```
docker run -v $PWD:/opt/keycloak/data/import \
  quay.io/keycloak/keycloak:latest \
  import --file /opt/keycloak/data/import/myrealm.json
```

#### **Required Permissions for Realm Creation**

- Users must have <span class="s1">manage-realm</span> or <span class="s1">admin</span> roles in the master realm.
- If using the REST API, token must be obtained using <span class="s1">admin-cli</span>.

To grant permissions:

```
# From master realm
Users > admin > Role Mappings > Realm Roles > Assign 'admin'
```

## **Best Practices for Creating Realms**

- **Use Descriptive Realm Names:** Avoid generic names like <span class="s2">test</span> or <span class="s2">default</span>. Use environment- or tenant-specific names like <span class="s2">dev-project-x</span>, <span class="s2">production-client123</span>.
- **Enable Login Hardening Features:** <span class="s3">Under </span>**Realm Settings &gt; Login**<span class="s3">:</span>
    - Enable email verification
    - Disable user registration (unless required)
    - Enable OTP for 2FA
- **Use Theme Branding:** Upload and assign a custom login theme under <span class="s4">**Themes**</span> to reflect client or environment branding.
- **Automate via REST or Terraform:** For CI/CD deployments, automate realm provisioning using REST API or tools like Terraform (<span class="s2">mrparkers/keycloak</span> provider).

## **Common Issues and Troubleshooting**

<table border="1" id="bkmrk-issue-possible-cause" style="border-collapse: collapse; border-color: rgb(0, 0, 0);"><thead><tr><th style="border-color: rgb(0, 0, 0);">**Issue**

</th><th style="border-color: rgb(0, 0, 0);">**Possible Cause**

</th><th style="border-color: rgb(0, 0, 0);">**Solution**

</th></tr></thead><tbody><tr><td style="border-color: rgb(0, 0, 0);"><span class="s1">403 Forbidden</span> when creating via API

</td><td style="border-color: rgb(0, 0, 0);">Access token lacks permission

</td><td style="border-color: rgb(0, 0, 0);">Ensure token is generated from a user with <span class="s1">admin</span> role in <span class="s1">master</span> realm

</td></tr><tr><td style="border-color: rgb(0, 0, 0);">Realm already exists

</td><td style="border-color: rgb(0, 0, 0);">Attempting to recreate an existing realm

</td><td style="border-color: rgb(0, 0, 0);">Use a different realm name or delete existing one before re-creating

</td></tr><tr><td style="border-color: rgb(0, 0, 0);">Realm not listed in dropdown

</td><td style="border-color: rgb(0, 0, 0);">Misconfiguration or missing role

</td><td style="border-color: rgb(0, 0, 0);">Refresh UI or check admin user’s permissions

</td></tr><tr><td style="border-color: rgb(0, 0, 0);">Docker import doesn’t create realm

</td><td style="border-color: rgb(0, 0, 0);">File format error or wrong path

</td><td style="border-color: rgb(0, 0, 0);">Ensure JSON is valid and mounted correctly in <span class="s1">/opt/keycloak/data/import</span>

</td></tr><tr><td style="border-color: rgb(0, 0, 0);">Login page shows default theme

</td><td style="border-color: rgb(0, 0, 0);">Custom theme not set

</td><td style="border-color: rgb(0, 0, 0);">Go to <span class="s1">**Realm Settings &gt; Themes**</span> and set your theme manually

</td></tr></tbody></table>