Zumri-Backend/Documentation/Auth-API.md

Authentication API

The Authentication API provides OTP-based login, access-token renewal, password recovery, current-user lookup, and logout.

Base URL

http://localhost:3070/api/auth

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:

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

Request body

{
  "email": "sathira@niolla.lk",
  "password": "Niolla@123"
}

Success response — 201 Created

{
  "success": true,
  "message": "OTP Sent Successfully"
}

Error responses

• 401 Unauthorized — invalid password
• 404 Not Found — user not found
• 500 Internal Server Error — OTP generation or email delivery failed

---

Login

Verifies the emailed OTP and creates an authenticated session. The user account must be active.

Endpoint: POST http://localhost:3070/api/auth/login

Request body

{
  "email": "sathira@niolla.lk",
  "otp": "922304"
}

Success response — 200 OK

{
  "success": true,
  "message": "Login Successful",
  "data": {
    "id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
    "email": "sathira@niolla.lk",
    "firstName": "Sathira",
    "lastName": "Sri Sathsara",
    "role": null,
    "accountType": "admin",
    "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

Returns the authenticated user's token claims and effective permissions.

Endpoint: GET http://localhost:3070/api/auth/me

Authentication: Required

Request body

No request body.

Success response — 200 OK

{
  "authenticated": true,
  "user": {
    "id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
    "firstName": "Sathira",
    "lastName": "Sri Sathsara",
    "email": "sathira@niolla.lk",
    "accountType": "admin",
    "iat": 1778865265,
    "exp": 1778868865,
    "permissions": []
  }
}

Error responses

• 401 Unauthorized — token is missing, invalid, or expired

---

Refresh Session

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

Request body

No request body. The refresh_token cookie is required.

Success response — 200 OK

{
  "success": true,
  "message": "Session refreshed successfully"
}

Error response — 401 Unauthorized

Returned when the refresh cookie is missing or the session is invalid, expired, or no longer active.

---

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

Authentication: Not required

Request body

{
  "email": "sathira@niolla.lk"
}

Success response — 200 OK

{
  "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

Authentication: Not required

Request body

{
  "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

{
  "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

Request body

No request body.

Success response — 200 OK

{
  "success": true,
  "message": "Logged out successfully"
}

Error response — 500 Internal Server Error

{
  "success": false,
  "message": "Failed to logout"
}