Login - LearnWay Backend

LearnWay supports multiple login methods to accommodate diverse client scenarios.

Authenticate with either email or username and password. If TOTP 2FA is active, an intermediate TOTP challenge status is returned.

Endpoint

POST /api/v2/auth/login-with-password

Request Body

Field	Type	Required	Description
`email`	`string`	Yes	User email address or username
`password`	`string`	Yes	User account password

{
  "email": "john.doe@example.com",
  "password": "SecurePassword123!"
}

Response (200 OK - Standard)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john.doe@example.com",
    "username": "john_doe",
    "role": "USER",
    "country": "US",
    "isEmailVerified": true,
    "totalXP": 450,
    "totalGems": 35,
    "walletAddress": "0x71C...3921",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
    "expiresAt": "2026-08-22T22:00:00.000Z"
  },
  "message": "Login successful"
}

Response (200 OK - 2FA Required)

When TOTP multi-factor authentication is active on the account:

{
  "success": true,
  "data": {
    "is2FARequired": true,
    "tempToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
    "userId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "message": "Two-factor authentication required"
}

Authenticate directly using a one-time verification code sent to the user’s email.

Endpoint

POST /api/v2/auth/login-with-otp

Request Body

Field	Type	Required	Description
`email`	`string`	Yes	User email address
`otpCode`	`string`	Yes	6-digit numeric OTP code

{
  "email": "john.doe@example.com",
  "otpCode": "849201"
}

Response (200 OK)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john.doe@example.com",
    "username": "john_doe",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6..."
  },
  "message": "OTP verification and login successful"
}