Auth Endpoints

Create Account

POST /api/create-account

Request Body

Prop

Type

Example

curl -X POST http://localhost:3000/api/create-account \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "password": "SecurePass123!",
    "confirmPassword": "SecurePass123!"
  }'

{
  "success": true,
  "message": "Account created. Please verify your email.",
  "data": {
    "userId": "507f1f77bcf86cd799439011",
    "email": "john@example.com"
  }
}

{
  "success": false,
  "message": "Email already registered"
}

Authenticate with email and password.

POST /api/log-in

Request Body

Prop

Type

Example

curl -X POST http://localhost:3000/api/log-in \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "password": "SecurePass123!"
  }'

{
  "success": true,
  "message": "Login successful",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "session": {
      "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "browser": "Chrome 120",
      "os": "macOS 14",
      "device": "Desktop"
    },
    "user": {
      "userId": "507f1f77bcf86cd799439011",
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "username": "john"
    }
  }
}

{
  "success": false,
  "message": "Invalid email or password"
}

{
  "success": false,
  "message": "Please verify your email before logging in"
}

Logout

End the current session. Requires authentication.

POST /api/auth/logout

Headers

Authorization: Bearer <access-token>
X-Session-Id: <session-id>

Example

curl -X POST http://localhost:3000/api/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "X-Session-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890"

{
  "success": true,
  "message": "Logged out successfully"
}

Refresh Token

Get a new access token using the refresh token.

POST /api/auth/refresh-token

Headers

X-Session-Id: <session-id>

Request Body

Prop

Type

Example

curl -X POST http://localhost:3000/api/auth/refresh-token \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

{
  "success": true,
  "message": "Token refreshed",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "userId": "507f1f77bcf86cd799439011",
      "email": "john@example.com"
    }
  }
}

{
  "success": false,
  "message": "Invalid or expired refresh token"
}

The axios interceptor automatically handles token refresh when the access token expires.

Email Verification

Verify email address with OTP code.

POST /api/email-verification

Request Body

Prop

Type

Example

curl -X POST http://localhost:3000/api/email-verification \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "verificationCode": "847291"
  }'

{
  "success": true,
  "message": "Email verified successfully",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "session": {
      "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    "user": {
      "userId": "507f1f77bcf86cd799439011",
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "username": "john"
    }
  }
}

{
  "success": false,
  "message": "Invalid or expired verification code"
}

Resend Verification

Request a new verification code.

POST /api/email-verification/resend

Request Body

Prop

Type

Example

curl -X POST http://localhost:3000/api/email-verification/resend \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com"
  }'

{
  "success": true,
  "message": "Verification email sent",
  "data": {
    "email": "john@example.com"
  }
}

Resending generates a new OTP. Previous codes are invalidated.

Forgot Password

Request a password reset code.

POST /api/forgot-password

Request Body

Prop

Type

Example

curl -X POST http://localhost:3000/api/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com"
  }'

{
  "success": true,
  "message": "If an account exists, a reset email has been sent"
}

For security, this endpoint always returns success even if the email doesn't exist.

Reset Password

Set a new password using the reset code.

POST /api/reset-password

Request Body

Prop

Type

Example

curl -X POST http://localhost:3000/api/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "resetToken": "123456",
    "password": "NewSecurePass456!",
    "confirmPassword": "NewSecurePass456!"
  }'

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

{
  "success": false,
  "message": "Invalid or expired reset token"
}

On this page