Authentication API
API documentation for client and admin authentication endpoints
The HMS API provides separate authentication systems for Client and Admin users. Both systems use JWT-based authentication with HTTP-only cookies for secure token storage.
Authentication Flow
Client Authentication
- Registration: Clients can register with email, password, and name
- Login: Clients authenticate with email and password
- Token Management: Access tokens (15 min) and refresh tokens (7 days) are stored in HTTP-only cookies
- Protected Routes: Access to client resources requires a valid access token
Admin Authentication
- Login: Admins authenticate with email and password (no public registration)
- Token Management: Same token system as clients
- Role-Based Access: Admin routes verify both authentication and admin role
API Endpoints
Client Authentication
POST /api/v1/client/auth/register
Register a new client account.
Request Body:
{
"email": "[email protected]",
"password": "SecurePassword123!",
"name": "Client Name"
}Response: 201 Created
{
"id": "uuid",
"email": "[email protected]",
"name": "Client Name",
"emailVerified": false,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}Errors:
409 Conflict: Email already registered400 Bad Request: Validation error
POST /api/v1/client/auth/login
Authenticate a client and receive access tokens.
Request Body:
{
"email": "[email protected]",
"password": "SecurePassword123!"
}Response: 200 OK
{
"client": {
"id": "uuid",
"email": "[email protected]",
"name": "Client Name",
"emailVerified": true
},
"accessToken": "jwt-token",
"refreshToken": "jwt-refresh-token"
}Note: Tokens are also set as HTTP-only cookies.
Errors:
401 Unauthorized: Invalid credentials
POST /api/v1/client/auth/logout
Log out the current client (clears cookies).
Response: 200 OK
{
"message": "Logout successful"
}POST /api/v1/client/auth/forgot-password
Request a password reset link.
Request Body:
{
"email": "[email protected]"
}Response: 200 OK
{
"message": "If the email exists, a password reset link has been sent"
}Note: Always returns 200 to prevent email enumeration.
POST /api/v1/client/auth/reset-password
Reset password using a token from email.
Request Body:
{
"token": "reset-token-from-email",
"newPassword": "NewSecurePassword123!"
}Response: 200 OK
{
"message": "Password reset successful"
}Errors:
400 Bad Request: Invalid or expired token
GET /api/v1/client/auth/profile
Get the authenticated client's profile.
Headers:
Cookie: accessToken=<token>
Response: 200 OK
{
"id": "uuid",
"email": "[email protected]",
"name": "Client Name",
"emailVerified": true,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}Errors:
401 Unauthorized: Missing or invalid token
PUT /api/v1/client/auth/profile
Update the authenticated client's profile.
Headers:
Cookie: accessToken=<token>
Request Body:
{
"name": "Updated Name",
"email": "[email protected]"
}Response: 200 OK
{
"id": "uuid",
"email": "[email protected]",
"name": "Updated Name",
"emailVerified": true,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}Errors:
401 Unauthorized: Missing or invalid token400 Bad Request: Validation error
Admin Authentication
POST /api/v1/admin/auth/login
Authenticate an admin user.
Request Body:
{
"email": "[email protected]",
"password": "AdminPassword123!"
}Response: 200 OK
{
"admin": {
"id": "uuid",
"email": "[email protected]",
"name": "Admin Name",
"role": "admin",
"emailVerified": true
},
"accessToken": "jwt-token",
"refreshToken": "jwt-refresh-token"
}Errors:
401 Unauthorized: Invalid credentials
POST /api/v1/admin/auth/logout
Log out the current admin (clears cookies).
Response: 200 OK
{
"message": "Logout successful"
}POST /api/v1/admin/auth/forgot-password
Request a password reset link for admin.
Request Body:
{
"email": "[email protected]"
}Response: 200 OK
{
"message": "If the email exists, a password reset link has been sent"
}POST /api/v1/admin/auth/reset-password
Reset admin password using a token from email.
Request Body:
{
"token": "reset-token-from-email",
"newPassword": "NewSecurePassword123!"
}Response: 200 OK
{
"message": "Password reset successful"
}GET /api/v1/admin/auth/profile
Get the authenticated admin's profile.
Headers:
Cookie: accessToken=<token>
Response: 200 OK
{
"id": "uuid",
"email": "[email protected]",
"name": "Admin Name",
"role": "admin",
"emailVerified": true,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}PUT /api/v1/admin/auth/profile
Update the authenticated admin's profile.
Headers:
Cookie: accessToken=<token>
Request Body:
{
"name": "Updated Admin Name",
"email": "[email protected]"
}Response: 200 OK
{
"id": "uuid",
"email": "[email protected]",
"name": "Updated Admin Name",
"role": "admin",
"emailVerified": true,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}Security Considerations
Token Storage
- Access tokens and refresh tokens are stored in HTTP-only cookies
- Cookies are marked as
Securein production (HTTPS only) - Cookies use
SameSite=Laxto prevent CSRF attacks
Token Expiration
- Access Token: 15 minutes
- Refresh Token: 7 days
- Expired tokens are automatically rejected
Password Security
- Passwords are hashed using bcrypt with salt rounds
- Minimum password requirements should be enforced on the frontend
- Password reset tokens expire after 1 hour and are single-use
Rate Limiting
- Implement rate limiting on authentication endpoints to prevent brute force attacks
- Recommended: 5 attempts per 15 minutes per IP
Email Enumeration Prevention
- Password reset endpoints always return 200 OK, regardless of whether the email exists
- This prevents attackers from discovering valid email addresses
CORS Configuration
- API is configured to accept requests only from authorized frontend origins
- Credentials are required for cookie-based authentication
Error Handling
All authentication endpoints return consistent error responses:
{
"error": "Error message description"
}Common HTTP status codes:
200 OK: Success201 Created: Resource created400 Bad Request: Validation error401 Unauthorized: Authentication required or failed403 Forbidden: Insufficient permissions409 Conflict: Resource conflict (e.g., duplicate email)