Description
The application currently exposes a frontend authentication interface at /auth without a fully implemented and unified backend authentication mechanism for a single consistent flow.
This issue introduces a minimal OTP-based authentication system (MVP) that enables users to sign in using their phone number. The goal is to establish a complete end-to-end authentication flow between frontend and backend while keeping the implementation lightweight, testable, and production-ready for future extension.
Objectives
- Implement a complete OTP-based authentication flow in backend
- Support phone-number-only login (MVP scope)
- Ensure JWT token generation after successful OTP verification
- Enable automatic user creation on first successful login
- Ensure compatibility with existing frontend
/auth page
- Maintain a clean and minimal authentication architecture
Requirements
Endpoint Specification
1. Request OTP
POST /auth/otp/request
Payload
- Verify OTP
POST /auth/otp/verify
Payload
{
"phone": "string",
"code": "string"
}
Core Logic
Generate a 6-digit OTP for authentication
Store OTP with expiration time (10 minutes)
Validate OTP against latest unused record for the phone number
Mark OTP as used after successful verification
Create a new user if one does not exist for the phone number
Issue a JWT token on successful verification
Include basic user details in the response
Response Format
Success Response
{
"message": "OTP verified",
"accessToken": "string (JWT)",
"user": {
"id": "string",
"phone": "string",
"role": "renter"
}
}
Failure Responses
###Invalid or Expired OTP
401 Unauthorized
{
"message": "Invalid or expired OTP"
}
Missing Fields
400 Bad Request
{
"message": "Phone and code required"
}
Impact
Enables a complete authentication flow for the /auth frontend route
Provides secure JWT-based session handling for users
Removes dependency on password-based authentication for MVP scope
Establishes a scalable foundation for future enhancements (OAuth, refresh tokens, password auth)
Ensures proper frontend-backend integration for login flow
Description
The application currently exposes a frontend authentication interface at
/authwithout a fully implemented and unified backend authentication mechanism for a single consistent flow.This issue introduces a minimal OTP-based authentication system (MVP) that enables users to sign in using their phone number. The goal is to establish a complete end-to-end authentication flow between frontend and backend while keeping the implementation lightweight, testable, and production-ready for future extension.
Objectives
/authpageRequirements
Endpoint Specification
1. Request OTP
POST /auth/otp/requestPayload
{ "phone": "string" }POST /auth/otp/verify
Payload
{ "phone": "string", "code": "string" }Core Logic
Generate a 6-digit OTP for authentication
Store OTP with expiration time (10 minutes)
Validate OTP against latest unused record for the phone number
Mark OTP as used after successful verification
Create a new user if one does not exist for the phone number
Issue a JWT token on successful verification
Include basic user details in the response
Response Format
Success Response
{ "message": "OTP verified", "accessToken": "string (JWT)", "user": { "id": "string", "phone": "string", "role": "renter" } }Failure Responses
###Invalid or Expired OTP
401 Unauthorized
{ "message": "Invalid or expired OTP" }Missing Fields
400 Bad Request
{ "message": "Phone and code required" }Impact
Enables a complete authentication flow for the /auth frontend route
Provides secure JWT-based session handling for users
Removes dependency on password-based authentication for MVP scope
Establishes a scalable foundation for future enhancements (OAuth, refresh tokens, password auth)
Ensures proper frontend-backend integration for login flow