ERP_Auth_Service/API_DOCUMENTATION.md

# AuthHex API Documentation

Base route: `api`
All endpoints are `[AllowAnonymous]` at the HTTP layer, but individual functions may require a Bearer JWT (read via `HttpContext` claims) — noted per function below.

## Common envelope

**Request** (`ApiRequest`)
```json
{
  "functionName": "string (required, ignored for dedicated routes below)",
  "payload": { "...": "function-specific object" },
  "reference": "string (required, can be empty)"
}
```

**Response** (`ApiResponse`)
```json
{
  "statusCode": 200,
  "success": true,
  "message": "success",
  "data": { "...": "function-specific object" }
}
```
Errors: `404` unknown function, `400` (`KeyNotFoundException`/`InvalidOperationException`), `500` (`ArgumentException`).

---

## Routes

| Route | Method | Dispatches to | FunctionName |
|---|---|---|---|
| `/api/status` | GET | — | — (health check) |
| `/api/user` | POST | UserManager | from body |
| `/api/recovery` | POST | RecoveryManager | from body |
| `/api/registerUser` | POST | UserManager | forced `registerUser` |
| `/api/loginUser` | POST | UserManager | forced `loginUser` |
| `/api/forgotPassword` | POST | RecoveryManager | forced `forgotPassword` |
| `/api/alt` | POST | AltOptionManager | from body |
| `/api/role` | POST | RoleManager | from body |

### GET /api/status
Response:
```json
{ "status": "API is running", "timestamp": "2026-07-03T00:00:00Z" }
```

---

## /api/user — UserManager functions

### registerUser
Payload:
```json
{
  "userId": "guid (required)",
  "fullname": "string?",
  "userName": "string?",
  "nic": "string?",
  "email": "string?",
  "mobileNumber": "string?",
  "deviceName": "string? (default 'Unknown Device')",
  "roleId": "guid (required)",
  "userTypeId": "guid (required)",
  "chkUser": "bool? (if true, checks for existing conflicting user)",
  "password": "string? (auto-generated if empty)",
  "sendCredentialsEmail": "bool? (default true; emails `email` the username + password when set)"
}
```
The generated/supplied password is now persisted (hashed) against the user record (previously a bug left it unset). When `email` is present and `sendCredentialsEmail` is not `false`, an email with the username and password is sent best-effort after the user is committed (failures do not roll back registration).

Data:
```json
{
  "accessToken": "jwt",
  "refreshToken": "string",
  "expiresIn": 3600,
  "user": { "id": "guid", "fullName": "", "userName": "", "email": "", "mobileNumber": "", "emailVerified": false, "mobileNumberVerified": false, "isMfaEnabled": false, "roleId": "guid", "userTypeId": "guid" }
}
```

### loginUser
Payload:
```json
{
  "identifier": "string (required)",
  "password": "string?",
  "userTypeId": "guid?",
  "deviceName": "string? (default 'Unknown Device')"
}
```
Data: same shape as `registerUser` data.

### VerifyOtpForLogin
Payload:
```json
{ "referenceNumber": "string (required)", "otpCode": "string (required)", "deviceName": "string?" }
```
Data:
```json
{
  "success": true,
  "message": "OTP verified successfully.",
  "data": {
    "referenceNumber": "", "userId": "guid", "verified": true,
    "accessToken": "jwt", "refreshToken": "", "expiresIn": 3600,
    "user": { "...": "as above" }
  }
}
```

### refreshToken
Payload:
```json
{ "refreshToken": "string (required)", "deviceName": "string?" }
```
Data: same shape as `registerUser` data (rotates session).

### getUserDetails
Payload:
```json
{ "userId": "guid (required)" }
```
Data:
```json
{
  "id": "guid", "fullName": "", "userName": "", "email": "", "nic": "",
  "mobileNumber": "", "emailVerified": false, "mobileNumberVerified": false,
  "isMfaEnabled": false, "isActive": true, "isLocked": false, "createdAt": "",
  "role": { "roleId": "", "code": "", "name": "" },
  "userType": { "userTypeId": "", "code": "", "description": "" }
}
```

### listUserTypes
No payload.
Data: array of
```json
{ "userTypeId": "guid", "code": "", "description": "" }
```

### getUserSessions
_Requires auth (userId from claims). No payload needed._
Data: array of
```json
{ "sessionId": "", "deviceName": "", "browser": "", "os": "", "ipAddress": "", "createdAt": "", "expiresAt": "", "revokedAt": "", "isActive": true }
```

### ChangeUserStatus
_Requires auth._ Payload:
```json
{ "isActive": "bool (required)" }
```
Data: `{ "id", "fullName", "userName", "email", "mobileNumber", "isActive" }`

### LockUserAccount
_Requires auth._ Payload:
```json
{ "isLocked": "bool (required)" }
```
Data: `{ "id", "fullName", "userName", "email", "mobileNumber", "isLocked", "deletedAt" }`
(Also invalidates all user sessions.)

### ChangeUserPassword
_Requires auth._ Payload:
```json
{ "currentPassword": "string (required)", "newPassword": "string (required)" }
```
Data: `{ "message": "Password changed successfully" }`

### LogoutUser
Payload:
```json
{ "userId": "guid (required)" }
```
Data: `{ "message": "User logged out successfully" }`

### UpdateUser
_Requires auth._ Payload (all optional, at least one required):
```json
{
  "fullName": "string?", "userName": "string?", "nic": "string?", "address": "string?",
  "optional1": "string?", "optional2": "string?",
  "email": "string|null", "mobileNumber": "string|null",
  "currentPassword": "string? (required if newPassword set and existing password set)",
  "newPassword": "string?"
}
```
Data:
```json
{
  "message": "User updated successfully",
  "user": { "id", "fullName", "userName", "nic", "address", "optional1", "optional2", "email", "emailVerified", "mobileNumber", "mobileNumberVerified" }
}
```

### 2FA — initiateTwoFASetup
_Requires auth. No payload._
Data: third-party-service-defined setup result (QR/secret info).

### 2FA — completeTwoFASetup
_Requires auth._ Payload:
```json
{ "secretKey": "string (required)", "verificationCode": "string (required)" }
```
Data:
```json
{
  "message": "2FA setup completed successfully",
  "backupCodes": ["..."],
  "user": { "id", "fullName", "userName", "email", "isMfaEnabled" }
}
```

### 2FA — verifyTwoFA
_Requires auth._ Payload:
```json
{ "verificationCode": "string (required)" }
```
Data: raw third-party verification result object.

### 2FA — disableTwoFA
_Requires auth._ Payload:
```json
{ "verificationCode": "string (required)" }
```
Data:
```json
{ "message": "2FA has been disabled successfully", "user": { "id", "fullName", "userName", "email", "isMfaEnabled" } }
```

### 2FA — getTwoFAStatus
_Requires auth. No payload._
Data:
```json
{ "isMfaEnabled": false, "isVerified": false, "lastUsedAt": null, "verifiedAt": null, "hasBackupCodes": false }
```

---

## /api/recovery — RecoveryManager functions

### forgotPassword
Payload:
```json
{ "identifier": "string (required)", "useResetLink": "bool? (default false)", "numberOfDigits": "int? (default 6)" }
```
Data (useResetLink = true):
```json
{ "success": true, "message": "Password reset link sent to your email.", "data": { "referenceNumber": "", "expiresAt": "", "recoveryType": "ResetLink" } }
```
Data (useResetLink = false, OTP flow):
```json
{ "success": true, "message": "OTP sent successfully.", "data": { "referenceNumber": "", "expiresAt": "", "recoveryType": "OTP" } }
```

### verifyOTP
Payload:
```json
{ "referenceNumber": "string (required)", "otpCode": "string (required)" }
```
Data:
```json
{ "success": true, "message": "OTP verified successfully. You can now reset your password.", "data": { "referenceNumber": "", "userId": "guid", "verified": true } }
```

### resetPasswordWithToken
Payload:
```json
{ "resetToken": "string (required)", "newPassword": "string (required, min 8 chars)", "confirmPassword": "string (required, must match)" }
```
Data:
```json
{ "success": true, "message": "Password reset successful. Please login with your new password.", "data": { "userId": "guid", "email": "", "resetAt": "" } }
```

### resetPassword
Payload:
```json
{ "referenceNumber": "string (required)", "newPassword": "string (required, min 8 chars)", "confirmPassword": "string (required, must match)" }
```
(Requires recovery status = "Verified" via prior `verifyOTP` call.)
Data: same shape as `resetPasswordWithToken`.

---

## /api/alt — AltOptionManager functions

### IsAvailable
Payload:
```json
{ "Identifier": "string?", "Recovery": "string? (any non-null value flags recovery-mode)" }
```
Data (available): `{ "isAvailable": true, "message": "Identifier is available" }`
Data (taken, no Recovery): `{ "isAvailable": false, "message": "Identifier already in use" }`
Data (taken, Recovery set): `{ "existingUsers": [...] }`

### sendOtp
Payload:
```json
{ "identifier": "string (required, email or mobile)", "numberOfDigits": "int? (default 4)", "newUser": "bool? (default false)" }
```
Data (newUser = true):
```json
{ "success": true, "message": "OTP sent successfully for new user.", "data": { "referenceNumber": "", "expiresAt": "", "recoveryType": "OTP FOR NEW USER" } }
```
Data (existing user):
```json
{ "success": true, "message": "OTP sent successfully.", "data": { "referenceNumber": "", "expiresAt": "", "recoveryType": "OTP FOR LOGIN" } }
```

### VerifyOTP (alt)
Payload:
```json
{
  "userId": "guid?", "referenceNumber": "string (required)", "otpCode": "string (required)",
  "newUser": "bool? (default false)", "identifier": "string? (email/mobile/other — marks it verified on user)",
  "deviceName": "string? (default 'Unknown Device')"
}
```
Data:
```json
{
  "success": true,
  "message": "OTP verified successfully.",
  "data": {
    "referenceNumber": "", "userId": "guid", "verified": true,
    "accessToken": "jwt", "refreshToken": "", "expiresIn": 3600,
    "user": { "id", "fullName", "userName", "email", "mobileNumber", "emailVerified", "mobileNumberVerified", "isMfaEnabled", "roleId", "userTypeId" }
  }
}
```

---

## /api/role — RoleManager functions

> **Null-tolerant fields (fixed 2026-07-18):** `isSystemRole` is read via `data["isSystemRole"].ValueKind != JsonValueKind.Null`
> before calling `GetBoolean()` in both `createRole` and `updateRole` — an explicit JSON `null` (as opposed to the key being
> absent) previously threw an unhandled `InvalidOperationException`, surfaced to ERPCore callers as a generic `500`/`AUTH_UPSTREAM_ERROR`.

### createRole
Payload:
```json
{ "code": "string (required)", "name": "string? (defaults to code)", "isSystemRole": "bool? (default false)" }
```
Data:
```json
{ "roleId": "guid", "code": "", "name": "", "isSystemRole": false, "createdAt": "" }
```

### getRole
Payload:
```json
{ "roleId": "guid (required)" }
```
Data: same shape as `createRole`.

### listRoles
No payload.
Data: array of `createRole`-shaped objects.

### updateRole
Payload (all fields optional except `roleId`):
```json
{ "roleId": "guid (required)", "code": "string?", "name": "string?", "isSystemRole": "bool?" }
```
Data: same shape as `createRole`.

### deleteRole
Payload:
```json
{ "roleId": "guid (required)" }
```
Blocked with a `400` (`"ROLE_IN_USE: role is assigned to one or more users"`) if any `User.RoleId` references it (FK is `Restrict`).
Data: `{ "message": "Role deleted successfully" }`

---

## Notes
- All timestamps are UTC.
- `deviceName`, `Browser`, `OS`, `IPAddress` are captured per session from request headers for session tracking (`getUserSessions`).
- Password login validation (`PasswordHasher.Verify`) is performed in `loginUser` — invalid/missing password hashes are rejected.
- JWT access tokens issued with `expiresIn: 3600` (1 hour); refresh tokens/sessions expire after 30 days.