Authentication

User registration, login, email verification, and session management.

Base Route: /api/auth

---

Register

Creates a new user account and sends a verification email with a 6-digit code.

POST /api/auth/register

Request Body

{
  "email": "user@example.com",
  "password": "SecurePass123",
  "firstName": "John",
  "lastName": "Doe"
}

Field	Type	Required	Constraints
email	string	Yes	Valid email format
password	string	Yes	Min 8 chars, uppercase, lowercase, digit
firstName	string	No	Display name
lastName	string	No	Display name

Response 200 OK

{
  "success": true,
  "message": "Registration successful. Please check your email for the verification code.",
  "user": null
}

Error Responses

Status	Condition
400	Validation failure (weak password, invalid email)
400	Email already registered

---

Verify Email

Confirms the user's email address using the 6-digit code sent during registration.

POST /api/auth/verify-email

Request Body

{
  "email": "user@example.com",
  "code": "482910"
}

Field	Type	Required	Description
email	string	Yes	Account email
code	string	Yes	6-digit verification code

Response 200 OK

{
  "success": true,
  "message": "Email verified successfully.",
  "user": {
    "id": "a1b2c3d4-e5f6-...",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "roles": ["User"]
  }
}

Error Responses

Status	Condition
400	Invalid or expired code
400	Account locked due to too many failed attempts

Security Notes

• Codes expire after a configured time window
• Failed attempts are tracked; excessive failures trigger account lockout
• Lockout duration: 5 minutes after 5 failed attempts

---

Resend Verification Code

Resends the email verification code. Rate-limited to prevent abuse.

POST /api/auth/resend-code

Request Body

{
  "email": "user@example.com"
}

Response 200 OK

{
  "success": true,
  "message": "Verification code resent.",
  "user": null
}

Error Responses

Status	Condition
400	Rate limit exceeded (too many resend attempts)
400	Email not found or already verified

---

Login

Authenticates the user and sets a session cookie.

POST /api/auth/login

Request Body

{
  "email": "user@example.com",
  "password": "SecurePass123",
  "rememberMe": true
}

Field	Type	Required	Description
email	string	Yes	Account email
password	string	Yes	Account password
rememberMe	bool	No	Extended session persistence

Response 200 OK

Sets Set-Cookie header with authentication cookie.

{
  "success": true,
  "message": "Login successful.",
  "user": {
    "id": "a1b2c3d4-e5f6-...",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "roles": ["User"]
  }
}

Cookie Properties

Property	Value
HttpOnly	true
Secure	true
SameSite	Lax
Expiration	7 days (sliding)

Error Responses

Status	Condition
400	Invalid credentials
400	Email not verified
400	Account locked out

---

Get Current User

Returns the authenticated user's profile and roles.

GET /api/auth/me

Authorization: Required

Response 200 OK

{
  "success": true,
  "message": null,
  "user": {
    "id": "a1b2c3d4-e5f6-...",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "roles": ["User"]
  }
}

Error Responses

Status	Condition
401	No valid session

---

Logout

Terminates the authenticated session and clears the cookie.

POST /api/auth/logout

Authorization: Required

Response 200 OK

{
  "success": true,
  "message": "Logged out successfully.",
  "user": null
}

---

Response Schema: AuthResponse

interface AuthResponse {
  success: boolean;
  message: string | null;
  user: UserInfo | null;
}

interface UserInfo {
  id: string;
  email: string;
  firstName: string | null;
  lastName: string | null;
  roles: string[];
}