My App
Api

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

  1. Registration: Clients can register with email, password, and name
  2. Login: Clients authenticate with email and password
  3. Token Management: Access tokens (15 min) and refresh tokens (7 days) are stored in HTTP-only cookies
  4. Protected Routes: Access to client resources requires a valid access token

Admin Authentication

  1. Login: Admins authenticate with email and password (no public registration)
  2. Token Management: Same token system as clients
  3. 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 registered
  • 400 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 token
  • 400 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 Secure in production (HTTPS only)
  • Cookies use SameSite=Lax to 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: Success
  • 201 Created: Resource created
  • 400 Bad Request: Validation error
  • 401 Unauthorized: Authentication required or failed
  • 403 Forbidden: Insufficient permissions
  • 409 Conflict: Resource conflict (e.g., duplicate email)

On this page