Auth Module Documentation

This module provides endpoints and methods for user authentication, including login, logout, registration, and token refresh operations. It also includes a helper function to verify tokens.

Note: This module expects proper request payloads and uses DTOs (LoginDTO and RegisterDTO) to enforce data structure. Custom error handling is assumed to be in place.

Endpoints

Auth API Documentation

1. Login

POST /auth/login

Request Body

{
  "email": "[email protected]",
  "password": "yourPassword"
}

Success Response

Status: 200 OK

{
  "success": true,
  "message": "Login successful",
  "data": {
    "accessToken": "string",
    "userId": "string",
    "expiresAt": "2025-08-06T12:00:00.000Z",
    "auth": {
      "hasAccessToken": true,
      "enable": false,
      "status": "BASIC_AUTH",
      "verified": false
    }
  },
  "meta": {
    "timestamp": "2025-08-06T11:59:59.999Z"
  }
}

2. Admin Login

POST /auth/admin-login

Request Body

{
  "email": "[email protected]",
  "password": "adminPassword",
  "adminPassword": "superSecretAdminPassword"
}

Success Response

Status: 201 Created

{
  "success": true,
  "message": "Admin login successful",
  "data": {
    "message": "Admin authenticated",
    "auth": {
      "hasAccessToken": true,
      "enable": false,
      "status": "BASIC_AUTH",
      "verified": false
    }
  }
}

3. Logout

POST /auth/logout

Request Body

{
  "id": "userId"
}

Success Response

Status: 200 OK

{
  "success": true,
  "message": "Logout successful",
  "data": {
    "auth": {
      "hasAccessToken": false,
      "enable": false,
      "status": "LOGGED_OUT",
      "verified": false
    }
  }
}

4. Register

POST /auth/register

Request Body

{
  "email": "[email protected]",
  "name": "New User",
  "password": "userPassword",
  "role": "user",
  "adminPassword": "optionalAdminPassword"
}

Success Response

Status: 200 OK

{
  "success": true,
  "message": "Registration successful",
  "data": {
    "auth": {
      "hasAccessToken": false,
      "enable": false,
      "status": "REGISTERED",
      "verified": false
    }
  },
  "meta": {
    "status": true
  }
}

5. Refresh Token

POST /auth/refresh-token

Request Body

{
  "refreshToken": "yourRefreshToken"
}

Success Response

Status: 200 OK

{
  "success": true,
  "message": "Token refreshed successfully",
  "data": {
    "accessToken": "newAccessToken",
    "refreshToken": "newRefreshToken",
    "auth": {
      "hasAccessToken": true,
      "enable": false,
      "status": "BASIC_AUTH",
      "verified": false
    }
  }
}

6. 2FA Setup

POST /auth/2fa/setup

Headers

Authorization: Bearer <accessToken>

Request Body

None

Success Response

Status: 200 OK

{
  "success": true,
  "message": "2FA setup successful",
  "data": {
    "qrCode": "data:image/png;base64,...",
    "auth": {
      "hasAccessToken": true,
      "enable": false,
      "status": "NEEDS_SETUP"
    }
  },
  "meta": {
    "nextStep": "Scan the QR code and enter your first code to verify",
    "redirectTo": "/2fa-enable"
  }
}

7. Enable 2FA

POST /auth/2fa/enable

Headers

Authorization: Bearer <accessToken>

Request Body

{
  "userId": "userId",
  "token": "2faToken"
}

Success Response

Status: 200 OK

{
  "success": true,
  "message": "2FA enabled successfully",
  "data": {
    "isEnabled": true,
    "enabledAt": "2025-08-06T12:00:00.000Z",
    "auth": {
      "hasAccessToken": true,
      "enable": true,
      "status": "PENDING_VERIFICATION"
    }
  },
  "meta": {
    "nextStep": "Proceed to verify with a valid 2FA token",
    "redirectTo": "/verify-2fa"
  }
}

8. Verify 2FA

POST /auth/2fa/verify

Request Body

{
  "userId": "userId",
  "token": "2faVerificationToken"
}

Success Response

Status: 200 OK

{
  "success": true,
  "message": "2FA verification successful",
  "data": {
    "token": "accessToken",
    "refreshToken": "refreshToken",
    "user": {
      "id": "userId",
      "email": "[email protected]",
      "name": "User Name",
      "role": "user"
    },
    "auth": {
      "hasAccessToken": true,
      "enable": true,
      "status": "FULL_AUTH",
      "verified": true
    }
  },
  "meta": {
    "recommendation": "You're fully authenticated",
    "redirectTo": "/"
  }
}

9. Disable 2FA

POST /auth/2fa/disable

Headers

Authorization: Bearer <accessToken>

Request Body

{
  "token": "current2faToken"
}

Success Response

Status: 200 OK

{
  "success": true,
  "message": "2FA disabled successfully",
  "data": {
    "disabledAt": "2025-08-06T12:00:00.000Z",
    "auth": {
      "hasAccessToken": true,
      "enable": false,
      "status": "BASIC_AUTH",
      "verified": false
    }
  },
  "meta": {
    "securityNote": "Account now relies only on password. Re-enable 2FA for better security.",
    "redirectTo": "/login"
  }
}

Notes

• All endpoints returning tokens require secure HTTPS connections.
• 2FA setup, enable, verify, and disable require authentication with a valid access token (sent in the Authorization header).
• Request bodies use DTOs as defined in the controller (LoginDTO, RegisterDTO, ITwoFactorEnable, ITwoFactorVerify, etc.).
• Error responses will follow the format:

{
  "success": false,
  "error": "Error message"
}

License

This module is released under the MIT License.

This documentation provides an overview of the available endpoints and helper methods for authentication. For further details on business logic and DTO structures, please refer to the inline comments and source code within the module.