Authentication API Specification

Authentication API Specification

Base URL

/auth

---

Data Model

Table: Users

Field	Type	Constraints
id	UUID	Primary Key
firstName	varchar2	Not Null
lastName	varchar2
email	varchar2	Not Null, Unique
emailVerified	bool	Default: false
mobile	varchar2	Not Null, Unique
mobileVerified	bool	Default: false
googleId	varchar2	Unique
role	enum	Default: USER (Roles like ADMIN will be added later)
lastLogout	timestamp	Timestamp when the user last logged out
createdAt	timestamp	Auto-generated
updatedAt	timestamp	Auto-updated

Table: HashedPassword

Field	Type	Constraints
id	UUID	Primary Key
userId	UUID	Foreign Key (Users.id)
hashedPassword	varchar2

---

Authentication Flow Overview

This API follows JWT-based access token and refresh token authentication. Both token types serve different purposes:

• Access Token: Short-lived, used for authenticating user actions.
• Refresh Token: Long-lived, used to obtain new access tokens.

Token Payload (for both tokens):

{
  "userId": "string",
  "userEmail": "string",
  "firstName": "string",
  "lastName": "string"
}

Note: User roles will be added to the token payload in future iterations. Token utility functions are kept separate to allow easy changes in payload without affecting core API logic.

---

Endpoints

1. POST /auth/signup

Description: Registers a new user using email and password. The password is hashed before storing it in the database.

Request Body:

{
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "mobile": "string",
  "password": "string"
}

Important Instructions:

• Password Hashing: Before storing the user’s password, hash the password using a secure algorithm such as bcrypt.
• Store the hashed password in the HashedPassword table linked to the user.

Response Codes:

• 201 Created: On successful signup.
• 400 Bad Request: On validation errors or if email/mobile already exists.

---

2. POST /auth/login

Description: Authenticates a user using email and password. Provides both access and refresh tokens upon successful login.

Request Body:

{
  "email": "string",
  "password": "string"
}

Process:

• Validate the email and password.
• Compare the provided password with the stored hashed password using a secure comparison method.
• Generate access and refresh tokens with the payload: userId, userEmail, firstName, lastName.

Response Codes:

• 200 OK: On successful login.
• 401 Unauthorized: If the credentials are incorrect.

---

3. POST /auth/google-signin

Description: Verifies user details via Google OAuth. Adds a new user to the database or updates their googleId if they already exist.

Request Body:

{
  "googleToken": "string"
}

Process:

• Verify the googleToken with Google’s OAuth service.
• If the user does not exist, create a new user record with the provided details.
• If the user already exists, update their googleId.

Response Codes:

• 200 OK: On successful sign-in.
• 400 Bad Request: If the Google token is invalid.

---

4. POST /auth/refresh-token

Description: Refreshes the access token using the refresh token provided by the user.

Request Body:

{
  "refreshToken": "string"
}

Process:

• Validate the refresh token.
• If valid, generate a new access token with the same payload structure: userId, userEmail, firstName, lastName.

Response Codes:

• 200 OK: On successful token refresh.
• 401 Unauthorized: If the refresh token is invalid or expired.

---

5. POST /auth/logout (Authenticated)

Description: Logs out the authenticated user by updating the lastLogout timestamp, invalidating all tokens issued before that time.

Request Headers:

Authorization: Bearer access_token_jwt

Process:

• Ensure the user is authenticated using the Authorization header.
• Update the lastLogout timestamp for the authenticated user to invalidate any tokens issued before this time.

Response Codes:

• 200 OK: On successful logout.
• 401 Unauthorized: If the user is not authenticated or the access token is invalid.

---

Security Guidelines

1. Password Hashing: Use a secure hashing algorithm like bcrypt to hash the user's password before storing it in the database.
2. Access Token Expiry: Access tokens should be short-lived (15-30 minutes).
3. Refresh Token Expiry: Refresh tokens should be long-lived (e.g., 7 days) but stored securely (e.g., HttpOnly cookies or secure storage).
4. HTTPS: Enforce HTTPS for all API calls to protect tokens in transit.
5. Token Revocation: Use the lastLogout timestamp in the Users table to invalidate tokens issued before the logout time.
6. Strong Passwords: Enforce strong password rules (e.g., minimum length, character variety).
7. Rate Limiting: Apply rate limiting to sensitive endpoints like /auth/login and /auth/signup to prevent brute-force attacks.

Token Utility Functions

1. Token Generation: Implement token generation functions separately to allow for easy modifications to the token payload (e.g., adding roles in future iterations).
   • Function to generate access and refresh tokens based on user details.
2. Token Validation: Separate utility functions for token validation, so changes in token structure (like adding roles) won’t affect the rest of the API.
3. Payload Flexibility: Keep the payload structure isolated in the token utility layer to ensure smooth transitions if new fields (such as roles) are added later.

---

Future Considerations

• Role-Based Access Control (RBAC): In future iterations, introduce roles (USER, ADMIN, etc.) to the token payload and implement RBAC to restrict access to certain endpoints based on user roles.
• Data Validation: Ensure robust validation for all input fields to prevent SQL injection or similar attacks.
• Error Handling: Provide consistent error handling across the API, returning descriptive messages for invalid tokens, missing fields, etc.