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

```text
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:

```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
{
  "email": "sathira@niolla.lk",
  "password": "Niolla@123"
}
```

### Success response — `201 Created`

```json
{
  "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](http://localhost:3070/api/auth/login)

### Request body

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

### Success response — `200 OK`

```json
{
  "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](http://localhost:3070/api/auth/me)

**Authentication:** Required

### Request body

No request body.

### Success response — `200 OK`

```json
{
  "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](http://localhost:3070/api/auth/refresh)

### Request body

No request body. The `refresh_token` cookie is required.

### Success response — `200 OK`

```json
{
  "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](http://localhost:3070/api/auth/forgot-password)

**Authentication:** Not required

### Request body

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

### 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

---

## 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](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:

```http
Authorization: Bearer <access-token>
```

### Request body

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

```json
{
  "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.

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

#### `401 Unauthorized`

Returned when authentication fails or the current password is incorrect.

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

#### `404 Not Found`

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

#### `500 Internal Server Error`

```json
{
  "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](http://localhost:3070/api/auth/logout)

### Request body

No request body.

### Success response — `200 OK`

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

### Error response — `500 Internal Server Error`

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