Documentation/Auth-API.md

@@ -1,14 +1,39 @@
-# Auth API
+# Authentication API
 
-#### Request OTP
+The Authentication API provides OTP-based login, access-token renewal, password recovery, current-user lookup, and logout.
 
-**Endpoint**
+## Base URL
 
-```
+```text
-POST: http://localhost:3070/api/auth/req-otp
+http://localhost:3070/api/auth
 ```
 
-**Request Body**
+Requests and responses use JSON unless otherwise stated.
+
+## Authentication
+
+After a successful login, the API returns an access token in the response and sets two HTTP-only cookies:
+
+- `access_token` — valid for 15 minutes
+- `refresh_token` — valid for 7 days
+
+Protected endpoints accept the access token through the `access_token` cookie or this header:
+
+```http
+Authorization: Bearer <access-token>
+```
+
+When using cookie authentication from a browser, send requests with credentials enabled.
+
+---
+
+## Request OTP
+
+Validates the user's email and password, then sends a one-time password to the registered email address.
+
+**Endpoint:** `POST` [http://localhost:3070/api/auth/req-otp](http://localhost:3070/api/auth/req-otp)
+
+### Request body
 
 ```json
 {
@@ -17,7 +42,7 @@ POST: http://localhost:3070/api/auth/req-otp
 }
 ```
 
-**Respond**
+### Success response — `201 Created`
 
 ```json
 {
@@ -26,17 +51,21 @@ POST: http://localhost:3070/api/auth/req-otp
 }
 ```
 
+### Error responses
+
+- `401 Unauthorized` — invalid password
+- `404 Not Found` — user not found
+- `500 Internal Server Error` — OTP generation or email delivery failed
+
 ---
 
-#### Login
+## Login
 
-**Endpoint**
+Verifies the emailed OTP and creates an authenticated session. The user account must be active.
 
-```
+**Endpoint:** `POST` [http://localhost:3070/api/auth/login](http://localhost:3070/api/auth/login)
-POST: http://localhost:3070/api/auth/login
-```
 
-**Request Body**
+### Request body
 
 ```json
 {
@@ -45,7 +74,7 @@ POST: http://localhost:3070/api/auth/login
 }
 ```
 
-**Respond**
+### Success response — `200 OK`
 
 ```json
 {
@@ -54,33 +83,40 @@ POST: http://localhost:3070/api/auth/login
   "data": {
     "id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
     "email": "sathira@niolla.lk",
-    "firstName": "Jhon",
+    "firstName": "Sathira",
-    "lastName": "Doe",
+    "lastName": "Sri Sathsara",
+    "role": null,
     "accountType": "admin",
-    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9......"
+    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
   }
 }
 ```
 
+The response also sets the `access_token` and `refresh_token` HTTP-only cookies.
+
+### Error responses
+
+- `400 Bad Request` — email or OTP is missing
+- `401 Unauthorized` — OTP is invalid or expired
+- `403 Forbidden` — account is not active
+- `404 Not Found` — user not found
+- `500 Internal Server Error` — login failed unexpectedly
+
 ---
 
-#### Get Current User
+## Get Current User
 
-**Endpoint**
+Returns the authenticated user's token claims and effective permissions.
 
-```
+**Endpoint:** `GET` [http://localhost:3070/api/auth/me](http://localhost:3070/api/auth/me)
-GET: http://localhost:3070/api/auth/me
-```
 
-**Authorization**: Required (Bearer token)
+**Authentication:** Required
 
-**Request Body**
+### Request body
 
-```
+No request body.
-No Body
-```
 
-**Response (200)**
+### Success response — `200 OK`
 
 ```json
 {
@@ -98,23 +134,116 @@ No Body
 }
 ```
 
+### Error responses
+
+- `401 Unauthorized` — token is missing, invalid, or expired
+
 ---
 
-### Logout
+## Refresh Session
 
-**Endpoint**
+Uses the HTTP-only refresh-token cookie to rotate the session and issue new access and refresh cookies.
 
-```
+**Endpoint:** `POST` [http://localhost:3070/api/auth/refresh](http://localhost:3070/api/auth/refresh)
-POST: http://localhost:3070/api/auth/logout
+
+### Request body
+
+No request body. The `refresh_token` cookie is required.
+
+### Success response — `200 OK`
+
+```json
+{
+  "success": true,
+  "message": "Session refreshed successfully"
+}
 ```
 
-**Request Body**
+### Error response — `401 Unauthorized`
 
-```
+Returned when the refresh cookie is missing or the session is invalid, expired, or no longer active.
-No Body
+
+---
+
+## Forgot Password
+
+Sends a password-reset link when an account exists for the supplied email. The same success response is returned for unknown email addresses to prevent account discovery.
+
+**Endpoint:** `POST` [http://localhost:3070/api/auth/forgot-password](http://localhost:3070/api/auth/forgot-password)
+
+**Authentication:** Not required
+
+### Request body
+
+```json
+{
+  "email": "sathira@niolla.lk"
+}
 ```
 
-**Respond**
+### Success response — `200 OK`
+
+```json
+{
+  "success": true,
+  "message": "If an account exists for this email, a password reset link has been sent."
+}
+```
+
+### Error responses
+
+- `400 Bad Request` — email is missing or invalid
+- `500 Internal Server Error` — the reset request could not be processed
+
+---
+
+## Reset Password
+
+Sets a new password using the token from the password-reset email. A successful reset invalidates all existing refresh sessions for the user.
+
+**Endpoint:** `POST` [http://localhost:3070/api/auth/reset-password](http://localhost:3070/api/auth/reset-password)
+
+**Authentication:** Not required
+
+### Request body
+
+```json
+{
+  "token": "password-reset-token",
+  "newPassword": "NewPassword@1234",
+  "confirmPassword": "NewPassword@1234"
+}
+```
+
+The new password must contain at least one uppercase letter, one lowercase letter, one symbol, and four digits. It must differ from the current password.
+
+### Success response — `200 OK`
+
+```json
+{
+  "success": true,
+  "message": "Password reset successfully. Please login again."
+}
+```
+
+### Error responses
+
+- `400 Bad Request` — fields are missing, passwords do not match, password rules are not met, the new password matches the current password, or the token is invalid or expired
+- `500 Internal Server Error` — password reset failed unexpectedly
+
+---
+
+## Logout
+
+Deletes the current refresh session when available and clears both authentication cookies.
+
+**Endpoint:** `POST` [http://localhost:3070/api/auth/logout](http://localhost:3070/api/auth/logout)
+
+### Request body
+
+No request body.
+
+### Success response — `200 OK`
 
 ```json
 {
@@ -122,3 +251,12 @@ No Body
   "message": "Logged out successfully"
 }
 ```
+
+### Error response — `500 Internal Server Error`
+
+```json
+{
+  "success": false,
+  "message": "Failed to logout"
+}
+```