User API Documentation
Base path: /user (mounted at /user)
All routes require keycloak.protect() — Bearer token authentication via Keycloak.
POST /user/:username/cashier-reset-password
Purpose: Reset a cashier's password to an auto-generated default. The default password is generated as: first 3 chars uppercase + 4th char lowercase + @ + last 4 chars of username. The password is set as temporary (user must change on next login).
Path Parameters
| Name |
Type |
Required |
Description |
| username |
string |
Yes |
Username of the cashier to reset |
Responses
| Code |
Body |
| 200 |
{ "message": "Password reset successfully" } |
| 400 |
{ "message": "Username is required" } |
| 404 |
{ "message": "No user found" } |
| 500 |
{ "message": "<error>" } |
POST /user/change-password
Purpose: Authenticated user changes their own password. Verifies old password against Keycloak token endpoint, then sets the new password as permanent.
Request Body
| Field |
Type |
Required |
Description |
| oldPassword |
string |
Yes |
Current password |
| newPassword |
string |
Yes |
New password |
| confirmPassword |
string |
Yes |
Must match newPassword |
Responses
| Code |
Body |
| 200 |
{ "message": "Password changed successfully" } |
| 400 |
{ "message": "All fields are required" } or "New passwords do not match" or "Invalid old password" |
| 401 |
{ "message": "Unauthorized: User" } |
| 404 |
{ "message": "No user found" } |
| 500 |
{ "message": "<error>" } |
POST /user/
Purpose: Create a cashier user in Keycloak tied to a specific merchant. The username must correspond to an existing terminal serial in TMS for the given merchantId.
Middleware
keycloak.protect()createUserValidationRules (express-validator)
Request Body
| Field |
Type |
Required |
Description |
| username |
string |
Yes |
Alphanumeric, must exist as serial in TMS |
| password |
string |
Yes |
Minimum 6 characters |
| role |
string |
Yes |
One of: "cashier", "merchant", "admin" |
| merchantId |
string |
Yes |
Merchant ID the user belongs to |
Responses
| Code |
Body |
| 201 |
{ "message": "User created successfully", "userId": "<keycloak-id>" } |
| 400 |
{ "errors": [...] } (validation) or { "message": "Serials did not exist in TMS" } |
| 500 |
{ "message": "<error>" } |
GET /user/merchant
Purpose: Get all cashier/terminal users belonging to a merchant. Fetches terminal serials from TMS for the given merchantId, then returns the corresponding Keycloak user data for each serial.
Query Parameters
| Name |
Type |
Required |
Description |
| merchantId |
string |
Yes |
Merchant ID to retrieve cashier users for |
Responses
| Code |
Body |
| 200 |
[{ "id": "...", "username": "...", "email": null, "firstName": null, "lastName": null, "enabled": true }] |
| 400 |
{ "message": "merchantId is required" } |
| 500 |
{ "message": "<error>" } |
GET /user/admin
Purpose: Get all admin users from Keycloak. Requires the authenticated user to have the "admin" client role.
Responses
| Code |
Body |
| 200 |
[{ "id": "...", "username": "...", "email": "...", "firstName": "...", "lastName": "...", "enabled": true }] |
| 400 |
{ "message": "permission is required" } |
| 500 |
{ "message": "<error>" } |
