---
title: "Create a realm user"
method: POST
path: "/clusters/{cluster_id}/realms/{realm_name}/users"
tags: ["Realm Users"]
---

# Create a realm user

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

## Request

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

Creates a user in the specified realm.

Required scope: `realm-users: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

- CreateRealmUserRequest: Request body for creating a realm user.
  - `username` string, required: Realm username. Allows letters, digits, dots, hyphens, underscores, and `@`.
  - `email` string, email, required
  - `first_name` string
  - `last_name` string
  - `temporary_password` string, password, required: Initial password set for the user. Must be at least 8 characters. Additional constraints are enforced by the realm's Keycloak password policy at the time of creation (e.g. minimum uppercase/lowercase/digit/special-character counts, disallow reuse, disallow username/email as password). Password policy violations return `422` with a message describing the specific rule that was not met.
  - `enabled` boolean: Whether the user can sign in immediately after creation.
  - `roles` RealmRoleName[]: Realm roles to assign after the user is created.

## Response `201`

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

- RealmUser: Public representation of a realm user.
  - `id` string, required
  - `username` string, required: Realm username. Allows letters, digits, dots, hyphens, underscores, and `@`.
  - `email` string, email, required
  - `first_name` string
  - `last_name` string
  - `enabled` boolean, required: Whether the user can sign in.
  - `email_verified` boolean: Whether the email address has been verified.
  - `organization` string: Organization associated with the user, when available.
  - `last_login_at` string, date-time: Most recent successful sign-in time, when available.
  - `created_at` string, date-time: Time when the user was created, when available.

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