Realms API

Realms are the top-level multi-tenancy boundary. Each realm has its own isolated users, roles, clients, and configuration.

List Realms

GET /api/realms
Authorization: Bearer <token>

curl -H "Authorization: Bearer $TOKEN" \
http://localhost:8080/api/realms

Response:

{
"content": [
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "master",
    "displayName": "Master Realm",
    "mfaRequired": false,
    "enabled": true,
    "createdAt": "2025-01-01T00:00:00Z"
  }
],
"totalElements": 1,
"totalPages": 1,
"page": 0,
"size": 20
}

Create Realm

POST /api/realms
Authorization: Bearer <token>
Content-Type: application/json

curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "acme-corp",
  "displayName": "ACME Corporation",
  "tokenLifespanSeconds": 300,
  "refreshTokenLifespanSeconds": 86400,
  "mfaRequired": false
}' \
http://localhost:8080/api/realms

Request body:

Field	Type	Required	Description
`name`	`string`	✅	Slug — `^[a-z0-9-]+$`, immutable after creation
`displayName`	`string`	—	Human-readable name
`tokenLifespanSeconds`	`integer`	—	Access token TTL (default: 300)
`refreshTokenLifespanSeconds`	`integer`	—	Refresh token TTL (default: 2592000)
`mfaRequired`	`boolean`	—	Enforce MFA for all logins (default: false)

Response: 201 Created with realm object.

Realm name is immutable

The name field is used as a unique key and cannot be changed after creation. Choose carefully.

Get Realm

GET /api/realms/{realmName}
Authorization: Bearer <token>

curl -H "Authorization: Bearer $TOKEN" \
http://localhost:8080/api/realms/acme-corp

Update Realm

PUT /api/realms/{realmName}
Authorization: Bearer <token>
Content-Type: application/json

curl -X PUT \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "displayName": "ACME Corp (Updated)", "mfaRequired": true }' \
http://localhost:8080/api/realms/acme-corp

Delete Realm

DELETE /api/realms/{realmName}
Authorization: Bearer <token>

curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
http://localhost:8080/api/realms/acme-corp

Response: 204 No Content

Deletion is permanent