> ## 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.

# TOTP Two-Factor Auth

> Configure authenticator app 2FA (Google Authenticator, Authy) with QR codes and backup recovery codes.

# TOTP Two-Factor Authentication

LearnWay supports Time-based One-Time Password (TOTP) compliant two-factor authentication (RFC 6238).

***

## Setup TOTP

Initiates TOTP configuration, generating a secret key, provisioning URI, and QR code Data URL for authenticator apps.

### Endpoint

```http theme={null}
POST /api/v2/auth/totp/setup
```

### Headers

```http theme={null}
Authorization: Bearer <jwt_access_token>
```

### Response (200 OK)

```json theme={null}
{
  "success": true,
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "otpauthUrl": "otpauth://totp/LearnWay:john.doe@example.com?secret=JBSWY3DPEHPK3PXP&issuer=LearnWay",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA..."
  },
  "message": "TOTP secret generated successfully. Please verify with a token to activate."
}
```

***

## Verify & Enable TOTP

Validates an initial code from the user's authenticator app to formally activate 2FA and returns recovery backup codes.

### Endpoint

```http theme={null}
POST /api/v2/auth/totp/verify
```

### Headers

```http theme={null}
Authorization: Bearer <jwt_access_token>
```

### Request Body

| Field   | Type     | Required | Description                              |
| :------ | :------- | :------- | :--------------------------------------- |
| `token` | `string` | **Yes**  | 6-digit TOTP code from authenticator app |

```json theme={null}
{
  "token": "492019"
}
```

### Response (200 OK)

```json theme={null}
{
  "success": true,
  "data": {
    "is2FAEnabled": true,
    "recoveryCodes": [
      "A1B2-C3D4-E5F6",
      "G7H8-I9J0-K1L2",
      "M3N4-O5P6-Q7R8",
      "S9T0-U1V2-W3X4"
    ]
  },
  "message": "Two-factor authentication enabled successfully"
}
```

***

## Disable TOTP

Disables 2FA on the account using a valid TOTP token or user password confirmation.

### Endpoint

```http theme={null}
POST /api/v2/auth/totp/disable
```

### Request Body

```json theme={null}
{
  "token": "492019",
  "password": "CurrentPassword123!"
}
```