# API Logout Endpoint Documentation

## 🚪 Logout Endpoint

### **POST /api/logout**

**Authentication:** Required (Sanctum token)

**Headers:**
```
Authorization: Bearer {access_token}
Content-Type: application/json
```

**Request Body:** None

**Response:**
```json
{
  "success": true,
  "message": "Logged out successfully"
}
```

**Error Responses:**

#### **401 Unauthorized**
```json
{
  "success": false,
  "message": "Unauthenticated."
}
```

#### **500 Server Error**
```json
{
  "success": false,
  "message": "Logout failed",
  "error": "Error details"
}
```

## 🔄 Frontend Integration

### **JavaScript Example:**
```javascript
class AuthManager {
  async logout() {
    try {
      const token = localStorage.getItem('auth_token');
      
      if (!token) {
        // Already logged out
        this.handleLogoutSuccess();
        return;
      }

      const response = await fetch('/api/logout', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        }
      });

      const data = await response.json();

      if (response.ok && data.success) {
        this.handleLogoutSuccess();
      } else {
        // Handle error but still clear local data
        console.error('Logout error:', data.message);
        this.handleLogoutSuccess();
      }
    } catch (error) {
      console.error('Network error during logout:', error);
      // Still clear local data on network error
      this.handleLogoutSuccess();
    }
  }

  handleLogoutSuccess() {
    // Clear local storage
    localStorage.removeItem('auth_token');
    localStorage.removeItem('user');
    
    // Clear any session data
    sessionStorage.clear();
    
    // Redirect to login page
    window.location.href = '/login';
  }
}

// Usage
const authManager = new AuthManager();
authManager.logout();
```

### **React Hook Example:**
```javascript
import { useState, useEffect } from 'react';

function useAuth() {
  const [isAuthenticated, setIsAuthenticated] = useState(false);

  const logout = async () => {
    try {
      const token = localStorage.getItem('auth_token');
      
      if (token) {
        await fetch('/api/logout', {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${token}`,
            'Content-Type': 'application/json'
          }
        });
      }
    } catch (error) {
      console.error('Logout error:', error);
    } finally {
      // Always clear local data
      localStorage.removeItem('auth_token');
      localStorage.removeItem('user');
      setIsAuthenticated(false);
      
      // Redirect
      window.location.href = '/login';
    }
  };

  return { logout, isAuthenticated };
}

// Usage in component
function LogoutButton() {
  const { logout } = useAuth();
  
  return <button onClick={logout}>Logout</button>;
}
```

### **React Native Example:**
```javascript
import AsyncStorage from '@react-native-async-storage/async-storage';

const logout = async () => {
  try {
    const token = await AsyncStorage.getItem('auth_token');
    
    if (token) {
      await fetch('/api/logout', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        }
      });
    }
  } catch (error) {
    console.error('Logout error:', error);
  } finally {
    // Always clear storage
    await AsyncStorage.multiRemove(['auth_token', 'user']);
    
    // Navigate to login screen
    navigation.navigate('Login');
  }
};
```

## 🔒 Security Features

### **Token Revocation**
- **All tokens deleted** - Logs user out from all devices
- **Immediate effect** - Tokens become invalid immediately
- **Server-side validation** - Tokens are verified on every request

### **Session Cleanup**
- **Local storage cleared** - Removes sensitive data
- **Session data cleared** - Clears any temporary session data
- **Redirect protection** - Redirects to login page

## 📱 Mobile App Considerations

### **iOS (Swift)**
```swift
func logout() {
    guard let token = UserDefaults.standard.string(forKey: "auth_token") else {
        navigateToLogin()
        return
    }
    
    var request = URLRequest(url: URL(string: "/api/logout")!)
    request.httpMethod = "POST"
    request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
    
    URLSession.shared.dataTask(with: request) { data, response, error in
        DispatchQueue.main.async {
            // Always clear local data
            UserDefaults.standard.removeObject(forKey: "auth_token")
            UserDefaults.standard.removeObject(forKey: "user")
            self.navigateToLogin()
        }
    }.resume()
}
```

### **Android (Kotlin)**
```kotlin
suspend fun logout() {
    try {
        val token = getSharedPreferences("auth", Context.MODE_PRIVATE)
            .getString("auth_token", null)
        
        if (token != null) {
            val response = apiService.logout("Bearer $token")
            // Handle response if needed
        }
    } catch (e: Exception) {
        Log.e("Logout", "Error during logout", e)
    } finally {
        // Always clear local data
        clearAuthData()
        navigateToLogin()
    }
}
```

## 🎯 Best Practices

### **Frontend:**
1. **Always clear local data** - Even if API call fails
2. **Handle network errors gracefully** - Don't trap user in app
3. **Redirect immediately** - Don't show logged-in content after logout
4. **Use proper HTTP methods** - POST for logout (not GET)

### **Backend:**
1. **Delete all tokens** - Force logout from all devices
2. **Use proper authentication** - Sanctum middleware
3. **Return consistent responses** - Success/error format
4. **Handle edge cases** - Invalid tokens, network errors

## 🔄 Complete Auth Flow

Now you have a complete authentication system:

1. **Login** → `POST /api/authenticate` (with 2FA support)
2. **Protected Routes** → Use `auth:sanctum` middleware
3. **Logout** → `POST /api/logout` (revokes all tokens)

Your frontend now has complete auth lifecycle management! 🎉