# 2FA API Documentation

This document describes the 2FA (Two-Factor Authentication) API endpoints for your Laravel backend.

## Endpoints

### 1. Generate 2FA Setup
```
POST /api/2fa/setup
```

**Authentication:** Required (Sanctum token)

**Request Body:** None

**Response:**
```json
{
  "success": true,
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qr_code_url": "https://api.qrserver.com/v1/create-qr-code/?data=...",
    "backup_codes": ["ABCD1234", "EFGH5678", "IJKL9012", "MNOP3456", "QRST7890", "UVWX1234", "YZAB5678", "CDEF9012"]
  }
}
```

**Description:** Generates a new 2FA secret and QR code URL for the user to set up authenticator app.

---

### 2. Verify 2FA Setup
```
POST /api/2fa/verify-setup
```

**Authentication:** Required (Sanctum token)

**Request Body:**
```json
{
  "secret": "JBSWY3DPEHPK3PXP",
  "code": "123456"
}
```

**Response:**
```json
{
  "success": true,
  "message": "2FA enabled successfully",
  "data": {
    "backup_codes": ["ABCD1234", "EFGH5678", "IJKL9012", "MNOP3456", "QRST7890", "UVWX1234", "YZAB5678", "CDEF9012"]
  }
}
```

**Description:** Verifies the 2FA code during setup and enables 2FA for the user.

---

### 3. Verify 2FA During Login
```
POST /api/2fa/verify
```

**Authentication:** Not required

**Request Body:**
```json
{
  "email": "user@example.com",
  "password": "password123",
  "code": "123456"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Authentication successful",
  "data": {
    "access_token": "1|abc123...",
    "user": {
      "id": 1,
      "email": "user@example.com",
      "role": 2,
      "google2fa_enabled_at": "2026-03-04T18:30:00.000000Z"
    }
  }
}
```

**Description:** Verifies credentials and 2FA code during login. Returns auth token if successful.

---

### 4. Disable 2FA
```
POST /api/2fa/disable
```

**Authentication:** Required (Sanctum token)

**Request Body:**
```json
{
  "password": "password123",
  "code": "123456"
}
```

**Response:**
```json
{
  "success": true,
  "message": "2FA disabled successfully"
}
```

**Description:** Disables 2FA for the authenticated user after password and 2FA verification.

## Error Responses

All endpoints return consistent error responses:

```json
{
  "success": false,
  "message": "Error description",
  "errors": {
    "field": ["Validation error message"]
  }
}
```

## Usage Flow

### Setup 2FA:
1. User logs in normally and gets auth token
2. Frontend calls `POST /api/2fa/setup` to get secret and QR code
3. User scans QR code with authenticator app
4. Frontend calls `POST /api/2fa/verify-setup` with secret and code
5. 2FA is enabled for the user

### Login with 2FA:
1. User enters email and password
2. Frontend calls `POST /api/2fa/verify` with credentials and 2FA code
3. Backend verifies everything and returns auth token
4. User is logged in

### Disable 2FA:
1. User must be authenticated
2. Frontend calls `POST /api/2fa/disable` with password and 2FA code
3. 2FA is disabled for the user

## Notes

- Backup codes are 8-character alphanumeric strings
- 2FA codes are 6-digit numbers from authenticator apps
- QR codes are compatible with Google Authenticator, Authy, etc.
- All sensitive data is properly encrypted and secured
- Rate limiting should be implemented on login attempts