Authentication API

Authentication endpoints for user login, registration, and token management.

Login

Authenticate a user and receive access tokens.

POST /api/auth/login

Request Body

{
  "email": "user@example.com",
  "password": "password123"
}

Response

{
  "success": true,
  "data": {
    "user": {
      "id": "60f7b3b3b3b3b3b3b3b3b3b3",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "user"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": "7d"
  },
  "message": "Login successful"
}

Example

const loginUser = async (email, password) => {
  try {
    const response = await fetch('/api/auth/login', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ email, password })
    });
    
    const result = await response.json();
    
    if (result.success) {
      // Store token in localStorage or cookie
      localStorage.setItem('token', result.data.token);
      return result.data.user;
    }
  } catch (error) {
    console.error('Login failed:', error);
  }
};

Register

Create a new user account.

POST /api/auth/register

Request Body

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "password123",
  "confirmPassword": "password123",
  "role": "user"
}

Response

{
  "success": true,
  "data": {
    "user": {
      "id": "60f7b3b3b3b3b3b3b3b3b3b3",
      "email": "john@example.com",
      "name": "John Doe",
      "role": "user",
      "isEmailVerified": false
    }
  },
  "message": "Registration successful. Please check your email for verification."
}

Refresh Token

Get a new access token using a refresh token.

POST /api/auth/refresh

Request Body

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": "7d"
  },
  "message": "Token refreshed successfully"
}

Logout

Invalidate the current session and tokens.

POST /api/auth/logout

Requires Authentication

Headers

Authorization: Bearer <your-token>

Response

{
  "success": true,
  "message": "Logout successful"
}

Forgot Password

Initiate password reset process.

POST /api/auth/forgot-password

Request Body

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

Response

{
  "success": true,
  "message": "Password reset email sent successfully"
}

Reset Password

Reset password using the reset token.

POST /api/auth/reset-password

Request Body

{
  "token": "reset-token-from-email",
  "password": "newpassword123",
  "confirmPassword": "newpassword123"
}

Response

{
  "success": true,
  "message": "Password reset successful"
}

Error Codes

Code	Description
INVALID_CREDENTIALS	Invalid email or password
USER_NOT_FOUND	User does not exist
EMAIL_ALREADY_EXISTS	Email is already registered
INVALID_TOKEN	Token is invalid or expired
PASSWORD_MISMATCH	Passwords do not match
WEAK_PASSWORD	Password does not meet requirements

Security Features

• Password Hashing: Passwords are hashed using bcrypt
• JWT Tokens: Secure token-based authentication
• PASETO Support: Modern token format support
• Rate Limiting: Login attempts are rate-limited
• Email Verification: Optional email verification
• Password Reset: Secure password reset via email