103 lines
3.5 KiB
Markdown
103 lines
3.5 KiB
Markdown
|
# 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>" }` |
|