Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
540 lines (418 loc) · 9.32 KB

API_DOCUMENTATION.md

File metadata and controls

540 lines (418 loc) · 9.32 KB

API Documentation

Base URL

http://localhost:5500

Environment Variables

The application requires the following environment variables:

Core Configuration

DATABASE_URL="file:./dev.db"
JWT_SECRET_KEY="your-secret-key"

Password Reset Configuration

PASSWORD_RESET_URL="http://localhost:3000/reset-password"
PASSWORD_RESET_TOKEN_EXPIRATION_HOURS=1

Two-Factor Authentication Configuration

TOTP_ISSUER="NodeJS Authentication Backend"
TOTP_BACKUP_CODES_COUNT=10

Email and SMS Providers

EMAIL_PROVIDER="console"
SMS_PROVIDER="console"

EMAIL_SERVICE_API_KEY=""
EMAIL_FROM="noreply@example.com"

SMS_SERVICE_API_KEY=""
SMS_FROM=""

Provider Options:

  • console - Logs to console (development only)
  • sendgrid - SendGrid email service (production)
  • twilio - Twilio SMS service (production)

Logging Configuration

NODE_ENV="development"
LOG_LEVEL="info"
LOG_DIR="logs"
LOG_TO_FILE="false"

Log Levels: error, warn, info, http, debug

Notes:

  • In development, logs are colorized and output to console
  • In production, logs are saved to files with daily rotation
  • Set LOG_TO_FILE="true" to enable file logging in development
  • Log files are automatically rotated daily with 30-day retention
  • Error logs and combined logs are stored in separate directories

Copy .env.example to .env and update with your values.

Authentication

Protected endpoints require a JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Health Check Endpoint

Health Check

GET /health

Returns the health status of the application and its dependencies.

Response: 200 OK (Healthy) or 503 Service Unavailable (Unhealthy)

{
  "status": "healthy",
  "timestamp": "2025-12-05T10:30:00.000Z",
  "uptime": 3600,
  "environment": "development",
  "database": {
    "status": "connected"
  },
  "memory": {
    "used": "45MB",
    "total": "128MB"
  }
}

Notes:

  • Public endpoint (no authentication required)
  • Useful for monitoring, load balancers, and orchestration tools
  • Database connectivity is verified on each request
  • All requests are logged with response time metrics

User Endpoints

Create User Account

POST /

Creates a new user account.

Request Body:

{
  "name": "John Doe",
  "username": "johndoe",
  "email": "john@example.com",
  "password": "SecurePass123"
}

Response: 201 Created

{
  "id": "01HF5P3NZQXW8K7VQZJ1Q9D8YM",
  "name": "John Doe",
  "username": "johndoe",
  "email": "john@example.com"
}

Errors:

  • 400 Bad Request - Invalid input data
  • 409 Conflict - Username or email already exists

Authenticate User

POST /login

Authenticates a user and returns JWT tokens.

Request Body:

{
  "username": "johndoe",
  "password": "SecurePass123"
}

Response: 200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "01HF5P3NZQXW8K7VQZJ1Q9D8YN"
}

Errors:

  • 400 Bad Request - Invalid credentials
  • 401 Unauthorized - Authentication failed

List All Users

GET /

Returns a list of all users (passwords excluded).

Headers:

Authorization: Bearer <token>

Response: 200 OK

[
  {
    "id": "01HF5P3NZQXW8K7VQZJ1Q9D8YM",
    "name": "John Doe",
    "username": "johndoe",
    "email": "john@example.com"
  }
]

Errors:

  • 401 Unauthorized - Missing or invalid token

Get User by ID

GET /:id

Returns a specific user by ID.

Headers:

Authorization: Bearer <token>

Response: 200 OK

{
  "id": "01HF5P3NZQXW8K7VQZJ1Q9D8YM",
  "name": "John Doe",
  "username": "johndoe",
  "email": "john@example.com"
}

Errors:

  • 401 Unauthorized - Missing or invalid token
  • 404 Not Found - User not found

Update User Account

PUT /:id

Updates user account information.

Headers:

Authorization: Bearer <token>

Request Body:

{
  "name": "John Updated",
  "email": "john.updated@example.com"
}

Response: 200 OK

{
  "id": "01HF5P3NZQXW8K7VQZJ1Q9D8YM",
  "name": "John Updated",
  "username": "johndoe",
  "email": "john.updated@example.com"
}

Errors:

  • 401 Unauthorized - Missing or invalid token
  • 404 Not Found - User not found

Delete User Account

DELETE /:id

Deletes a user account.

Headers:

Authorization: Bearer <token>

Response: 204 No Content

Errors:

  • 401 Unauthorized - Missing or invalid token
  • 404 Not Found - User not found

Password Reset Endpoints

Request Password Reset

POST /password/request

Initiates a password reset request. Sends an email with a reset token.

Request Body:

{
  "email": "john@example.com"
}

Response: 200 OK

{
  "message": "Password reset email sent successfully"
}

Errors:

  • 404 Not Found - User not found

Notes:

  • Reset token expires in 1 hour
  • Token can only be used once
  • Email is sent to the user's registered email address

Reset Password

POST /password/reset

Resets the user's password using the token received via email.

Request Body:

{
  "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "newPassword": "NewSecurePass123"
}

Response: 200 OK

{
  "message": "Password reset successfully"
}

Errors:

  • 400 Bad Request - Invalid or expired token
  • 404 Not Found - Token not found

Two-Factor Authentication Endpoints

All 2FA endpoints require authentication.

Enable 2FA

POST /2fa/enable

Initiates 2FA setup for the authenticated user.

Headers:

Authorization: Bearer <token>

Request Body:

{
  "method": "totp"
}

Available methods: totp, sms, email

Response: 200 OK

For TOTP method:

{
  "message": "2FA setup initiated successfully",
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "backupCodes": [
      "A1B2-C3D4",
      "E5F6-G7H8",
      "I9J0-K1L2"
    ]
  }
}

For SMS/Email methods:

{
  "message": "2FA setup initiated successfully",
  "data": {
    "backupCodes": [
      "A1B2-C3D4",
      "E5F6-G7H8",
      "I9J0-K1L2"
    ]
  }
}

Errors:

  • 401 Unauthorized - Missing or invalid token
  • 400 Bad Request - 2FA already enabled

Notes:

  • Save backup codes securely - they cannot be retrieved later
  • For TOTP: scan QR code with Google Authenticator or similar app
  • Backup codes can be used if primary method is unavailable

Verify 2FA

POST /2fa/verify

Verifies a 2FA token to complete authentication.

Headers:

Authorization: Bearer <token>

Request Body:

{
  "token": "123456"
}

Response: 200 OK

{
  "message": "2FA verified successfully",
  "verified": true
}

Errors:

  • 401 Unauthorized - Missing or invalid token
  • 400 Bad Request - Invalid 2FA token

Notes:

  • For TOTP: 6-digit code from authenticator app
  • For SMS/Email: code sent to user's phone/email
  • Tokens expire after a short time window

Verify Backup Code

POST /2fa/verify-backup

Verifies a backup code when primary 2FA method is unavailable.

Headers:

Authorization: Bearer <token>

Request Body:

{
  "code": "A1B2-C3D4"
}

Response: 200 OK

{
  "message": "Backup code verified successfully",
  "verified": true
}

Errors:

  • 401 Unauthorized - Missing or invalid token
  • 400 Bad Request - Invalid backup code

Notes:

  • Each backup code can only be used once
  • After use, the code is permanently invalidated
  • Generate new backup codes by disabling and re-enabling 2FA

Disable 2FA

DELETE /2fa/disable

Disables two-factor authentication for the authenticated user.

Headers:

Authorization: Bearer <token>

Response: 200 OK

{
  "message": "2FA disabled successfully"
}

Errors:

  • 401 Unauthorized - Missing or invalid token
  • 404 Not Found - 2FA not enabled for this user

HTTP Status Codes

Code Description
200 OK - Request successful
201 Created - Resource created successfully
204 No Content - Resource deleted successfully
400 Bad Request - Invalid input data
401 Unauthorized - Authentication required or failed
404 Not Found - Resource not found
409 Conflict - Resource already exists
500 Internal Server Error - Server error

Error Response Format

All error responses follow this format:

{
  "message": "Error description",
  "statusCode": 400
}

Security Notes

  1. Password Requirements:

    • Minimum length enforced by Password value object
    • Store passwords hashed with bcrypt

  2. JWT Tokens:

    • Include token in Authorization header as Bearer token
    • Tokens expire after configured time period
    • Refresh tokens stored in database with expiration

  3. 2FA Best Practices:

    • Store backup codes securely offline
    • TOTP secrets are base32 encoded
    • Use time-based windows for token validation

  4. Password Reset:

    • Tokens expire in 1 hour
    • Single-use only
    • Random 32-byte hex tokens

  5. Rate Limiting:

    • Implementation recommended for production
    • Particularly important for login, password reset, and 2FA endpoints