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

---

Change Password

Changes the authenticated user's password. After a successful change, all refresh sessions are revoked, authentication cookies are cleared, and the user must log in again.

Endpoint: POST http://localhost:3070/api/auth/change-password

Authentication: Required

The access token may be supplied through the access_token cookie or as a Bearer token:

Authorization: Bearer <access-token>

Request body

{
  "currentPassword": "CurrentPassword@1234",
  "newPassword": "NewPassword@5678",
  "confirmPassword": "NewPassword@5678"
}

The new password:

• Must match confirmPassword
• Must differ from the current password
• Must contain at least one uppercase letter
• Must contain at least one lowercase letter
• Must contain at least one symbol
• Must contain at least four digits

Success response — 200 OK

{
  "success": true,
  "message": "Password changed successfully. Please login again."
}

Error responses

400 Bad Request

Returned when required fields are missing, the passwords do not match, the new password does not satisfy the password policy, or it matches the current password.

{
  "success": false,
  "message": "New password and confirm password do not match"
}

401 Unauthorized

Returned when authentication fails or the current password is incorrect.

{
  "success": false,
  "message": "Current password is incorrect"
}

404 Not Found

{
  "success": false,
  "message": "User not found"
}

500 Internal Server Error

{
  "success": false,
  "message": "Failed to change password"
}

---

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