Authentication System Documentation

File: Authentication System Documentation.markdown

Loading documentation...

# Creator Platform Authentication System Documentation

## Overview
The Creator Platform features a comprehensive multi-method authentication system that supports both traditional password-based login and modern one-time password (OTP) authentication. The system is built with Laravel 12, uses Sanctum for API token management, and provides a seamless user experience across all authentication methods.

## 🔐 Authentication Methods Supported

### 1. Password-Based Authentication
- **Email + Password**: Login using email address and password
- **Phone + Password**: Login using phone number and password  
- **Username + Password**: Login using username and password

### 2. One-Time Password (OTP) Authentication
- **Email + OTP**: Receive 8-digit code via email (✅ **LIVE**)
- **Phone + OTP**: Receive 8-digit code via SMS (✅ **LIVE**)

### 3. User Registration
- Complete registration form with real-time validation
- Username availability checking
- Email availability checking
- Phone availability checking
- Role selection (creator/viewer)
- **Verification required for OTP login**

### 4. Account Management
- **Profile Updates**: Change name and role
- **Phone Number Changes**: Secure phone number updates with verification
- **Password Changes**: Secure password updates with current password verification
- **Email/Phone Verification**: Manual verification process for OTP login

### 5. Password Recovery
- **Email Password Reset**: Reset password via email link
- **SMS Password Reset**: Reset password via SMS OTP

## 🗄️ Database Structure

### Users Table
```sql
users:
- id (bigint, primary key)
- username (string, unique) - URL-safe identifier for profiles
- name (string) - Full name
- email (string, unique) - Email address
- phone (string, nullable, unique) - E.164 format phone number
- password (string, hashed) - Bcrypt hashed password
- role (enum: 'creator', 'viewer', 'admin') - User role
- email_verified_at (timestamp, nullable) - Email verification timestamp
- phone_verified_at (timestamp, nullable) - Phone verification timestamp
- two_factor_enabled (boolean, default false) - 2FA status
- created_at, updated_at (timestamps)
```

### Login Tokens Table
```sql
login_tokens:
- id (bigint, primary key)
- user_id (bigint, foreign key) - References users.id
- token (string, unique) - 8-digit OTP token
- type (enum: 'email', 'phone', 'phone_change', 'password_reset') - Token purpose
- expires_at (timestamp) - Token expiration (10 minutes)
- created_at, updated_at (timestamps)
```

### Personal Access Tokens Table (Sanctum)
```sql
personal_access_tokens:
- id (bigint, primary key)
- tokenable_type (string) - Model class name
- tokenable_id (bigint) - Model ID
- name (string) - Token name
- token (string, unique) - Hashed token
- abilities (text, nullable) - Token permissions
- last_used_at (timestamp, nullable) - Last usage
- expires_at (timestamp, nullable) - Expiration
- created_at, updated_at (timestamps)
```

## 🚀 API Endpoints

### Authentication Endpoints

#### POST `/api/login`
**Description**: Handle login attempts with multiple methods

**Request Body**:
```json
{
    "identifier": "user@example.com", // email, phone, or username
    "method": "password", // "password" or "otp"
    "password": "password123", // required for password method
    "token": "12345678" // required for OTP verification
}
```

**Response (Password Login Success)**:
```json
{
    "success": true,
    "message": "Login successful.",
    "user": {
        "id": 1,
        "username": "testuser",
        "name": "Test User",
        "email": "test@example.com",
        "phone": "+1234567890",
        "role": "podcaster",
        "email_verified_at": "2024-06-27T22:00:00.000000Z",
        "phone_verified_at": "2024-06-27T22:00:00.000000Z"
    },
    "token": "1|abc123def456..."
}
```

**Response (OTP Sent)**:
```json
{
    "success": true,
    "message": "OTP sent to your email.",
    "token": "12345678", // Remove in production
    "expires_at": "2024-06-27T23:00:00.000000Z"
}
```

#### POST `/api/register`
**Description**: Register new user account

**Request Body**:
```json
{
    "username": "newuser",
    "name": "New User",
    "email": "newuser@example.com",
    "phone": "+1234567890", // optional
    "password": "password123",
    "password_confirmation": "password123",
    "role": "creator" // "creator" or "viewer"
}
```

**Response**:
```json
{
    "success": true,
    "message": "Registration successful!",
    "user": {
        "id": 2,
        "username": "newuser",
        "name": "New User",
        "email": "newuser@example.com",
        "phone": "+1234567890",
        "role": "podcaster",
        "email_verified_at": null,
        "phone_verified_at": null
    },
    "token": "2|xyz789abc123..."
}
```

#### POST `/api/check-username`
**Description**: Check username availability

**Request Body**:
```json
{
    "username": "testuser"
}
```

**Response**:
```json
{
    "success": true,
    "available": false,
    "message": "Username is already taken."
}
```

#### POST `/api/check-email`
**Description**: Check email availability

**Request Body**:
```json
{
    "email": "test@example.com"
}
```

**Response**:
```json
{
    "success": true,
    "available": false,
    "message": "Email is already registered."
}
```

#### POST `/api/check-phone`
**Description**: Check phone availability

**Request Body**:
```json
{
    "phone": "+1234567890"
}
```

**Response**:
```json
{
    "success": true,
    "available": false,
    "message": "Phone number is already registered."
}
```

### Verification Endpoints

#### POST `/api/send-verification-email`
**Description**: Send email verification code

**Request Body**:
```json
{
    "email": "user@example.com"
}
```

**Response**:
```json
{
    "success": true,
    "message": "Verification email sent successfully.",
    "expires_at": "2024-06-27T23:00:00.000000Z"
}
```

#### POST `/api/verify-email`
**Description**: Verify email with code

**Request Body**:
```json
{
    "email": "user@example.com",
    "token": "12345678"
}
```

**Response**:
```json
{
    "success": true,
    "message": "Email verified successfully."
}
```

#### POST `/api/send-verification-phone`
**Description**: Send phone verification code

**Request Body**:
```json
{
    "phone": "+1234567890"
}
```

**Response**:
```json
{
    "success": true,
    "message": "Verification SMS sent successfully.",
    "expires_at": "2024-06-27T23:00:00.000000Z"
}
```

#### POST `/api/verify-phone`
**Description**: Verify phone with code

**Request Body**:
```json
{
    "phone": "+1234567890",
    "token": "12345678"
}
```

**Response**:
```json
{
    "success": true,
    "message": "Phone verified successfully."
}
```

### Password Reset Endpoints

#### POST `/api/password/reset/email`
**Description**: Send password reset email

**Request Body**:
```json
{
    "email": "user@example.com"
}
```

**Response**:
```json
{
    "success": true,
    "message": "Password reset email sent successfully.",
    "expires_at": "2024-06-27T23:00:00.000000Z"
}
```

#### POST `/api/password/reset/sms`
**Description**: Send password reset SMS

**Request Body**:
```json
{
    "phone": "+1234567890"
}
```

**Response**:
```json
{
    "success": true,
    "message": "Password reset SMS sent successfully.",
    "expires_at": "2024-06-27T23:00:00.000000Z"
}
```

#### POST `/api/password/reset`
**Description**: Reset password with token

**Request Body**:
```json
{
    "identifier": "user@example.com", // email or phone
    "token": "12345678",
    "password": "newpassword123",
    "password_confirmation": "newpassword123"
}
```

**Response**:
```json
{
    "success": true,
    "message": "Password reset successfully."
}
```

### Protected Profile Management Endpoints

#### GET `/api/user`
**Description**: Get current user information