Users API

Manage users within a realm. All user operations are scoped to a specific realm.

List Users

GET /api/users?realm={realm}&page=0&size=20
Authorization: Bearer <token>

curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:8080/api/users?realm=master&page=0&size=20"

Query parameters:

Parameter	Type	Default	Description
`realm`	`string`	✅ required	Realm name
`page`	`integer`	`0`	Page number (zero-based)
`size`	`integer`	`20`	Page size (max 100)

Create User

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

curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "realmName": "master",
  "username": "alice",
  "email": "alice@example.com",
  "firstName": "Alice",
  "lastName": "Smith",
  "password": "SecurePass123!"
}' \
http://localhost:8080/api/users

Request body:

Field	Type	Required	Description
`realmName`	`string`	✅	Target realm
`username`	`string`	✅	Must be unique within realm
`email`	`string`	✅	Must be unique within realm
`firstName`	`string`	—	Given name
`lastName`	`string`	—	Family name
`password`	`string`	✅	Plain-text — hashed BCrypt(12) server-side

Response: 201 Created

{
"id": "usr_abc123",
"realmName": "master",
"username": "alice",
"email": "alice@example.com",
"firstName": "Alice",
"lastName": "Smith",
"enabled": true,
"emailVerified": false,
"createdAt": "2025-06-01T10:00:00Z"
}

Get User

GET /api/users/{userId}
Authorization: Bearer <token>

Update User

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

curl -X PUT \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "firstName": "Alicia", "enabled": true }' \
http://localhost:8080/api/users/usr_abc123

Delete User

DELETE /api/users/{userId}
Authorization: Bearer <token>

Response: 204 No Content

Reset Password

PUT /api/users/{userId}/password
Authorization: Bearer <token>
Content-Type: application/json

curl -X PUT \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "newPassword": "NewSecurePass456!" }' \
http://localhost:8080/api/users/usr_abc123/password

Password hashing

Passwords are always stored as BCrypt hashes with cost factor 12. Plain-text passwords are never persisted.

Send Email Verification

POST /api/users/{userId}/send-verify-email
Authorization: Bearer <token>

Triggers a Kafka event → notification-service sends a verification email using the verify-email.html Thymeleaf template.