> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learnway.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Login

> Authenticate with password, email OTP, or TOTP second factor.

# Login

LearnWay supports multiple login methods to accommodate diverse client scenarios.

***

## Login with Password

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

### Endpoint

```http theme={null}
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          |

```json theme={null}
{
  "email": "john.doe@example.com",
  "password": "SecurePassword123!"
}
```

### Response (200 OK - Standard)

```json theme={null}
{
  "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:

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

***

## Login with OTP

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

### Endpoint

```http theme={null}
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 |

```json theme={null}
{
  "email": "john.doe@example.com",
  "otpCode": "849201"
}
```

### Response (200 OK)

```json theme={null}
{
  "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"
}
```