# API Authentication Guide - Mobile App Integration

## Overview
Your Laravel application is now fully configured with **Laravel Sanctum** token-based authentication, perfect for mobile app development.

## System Status ✅

### Completed Features
- ✅ User authentication with email/password
- ✅ Role-based access control (user, organizer, admin)
- ✅ Token generation and validation
- ✅ Protected API endpoints
- ✅ User favorites system
- ✅ Event management with permissions

### Test Users Available
All passwords are `password123`

| Email | Role | Purpose |
|-------|------|---------|
| user@example.com | user | Regular user - can view events & favorites |
| organizer@example.com | organizer | Can create/update/delete own events |
| admin@example.com | admin | Full system access |

---

## API Endpoints

### 1. Authentication Endpoints (PUBLIC)

#### Login
```
POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Response (200):
{
  "success": true,
  "message": "Login erfolgreich",
  "user": {
    "id": 1,
    "name": "Test User",
    "email": "user@example.com",
    "role": "user",
    "created_at": "2025-04-14T08:42:12.000000Z",
    "updated_at": "2025-04-14T08:42:12.000000Z"
  },
  "token": "1|PZHueLvJEr6d9mU1d4J7FUVJiPh0LD1Uy6S2Qc"
}
```

#### Register
```
POST /api/auth/register
Content-Type: application/json

{
  "name": "New User",
  "email": "newuser@example.com",
  "password": "password123",
  "password_confirmation": "password123",
  "role": "user"  // Optional: "user" (default), "organizer", or "admin"
}

Response (201): Similar to login response with new user token
```

### 2. Protected Endpoints (REQUIRE auth:sanctum)

All protected endpoints require the token in the Authorization header:
```
Authorization: Bearer YOUR_TOKEN_HERE
```

#### Get Current User
```
GET /api/auth/me
Authorization: Bearer 1|PZHueLvJEr6d9mU1d4J7FUVJiPh0LD1Uy6S2Qc
```

#### Update Profile
```
PUT /api/auth/profile
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "Updated Name",
  "email": "newemail@example.com"
}
```

#### Change Password
```
POST /api/auth/change-password
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "current_password": "password123",
  "password": "newpassword123",
  "password_confirmation": "newpassword123"
}
```

#### Logout
```
POST /api/auth/logout
Authorization: Bearer YOUR_TOKEN
```

### 3. Public Event Endpoints

#### List All Events
```
GET /api/events
```

#### Get Event Details
```
GET /api/events/{id}
```

#### Get Available Locations
```
GET /api/events/locations/list
```

#### Get Available Categories
```
GET /api/events/categories/list
```

### 4. Protected Event Management (Organizers Only)

#### Get My Events
```
GET /api/events/my-events
Authorization: Bearer YOUR_TOKEN
```

#### Create Event (Organizer/Admin Only)
```
POST /api/events
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "title": "New Event",
  "description": "Event description",
  "category": "Music",
  "location_id": 1,
  "website_url": "https://...",
  "contact_email": "contact@...",
  "contact_phone": "+49..."
}
```

#### Update Event (Creator Only)
```
PUT /api/events/{id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "title": "Updated Title",
  "description": "Updated description",
  ...
}
```

#### Delete Event (Creator Only)
```
DELETE /api/events/{id}
Authorization: Bearer YOUR_TOKEN
```

### 5. Favorites System

#### Toggle Favorite
```
POST /api/events/{id}/toggle-favorite
Authorization: Bearer YOUR_TOKEN
```

#### Get My Favorites
```
GET /api/events/favorites
Authorization: Bearer YOUR_TOKEN
```

---

## Mobile App Integration

### Authentication Flow

```
1. User enters email and password
   ↓
2. POST /api/auth/login
   ↓
3. Receive token from response
   ↓
4. Store token securely (e.g., keychain on iOS, Keystore on Android)
   ↓
5. Include token in all subsequent API calls:
   Authorization: Bearer {token}
   ↓
6. If token expires/401 error, prompt re-login
```

### Token Storage Best Practices

**iOS (Swift):**
```swift
// Store in Keychain
try keychain.store(token, key: "api_token")
let token = try keychain.retrieveString("api_token")
```

**Android (Kotlin):**
```kotlin
// Store in Encrypted SharedPreferences
val token = encryptedSharedPreferences.getString("api_token", null)
encryptedSharedPreferences.edit().putString("api_token", token).apply()
```

**Flutter:**
```dart
import 'package:flutter_secure_storage/flutter_secure_storage.dart';

const storage = FlutterSecureStorage();
await storage.write(key: "api_token", value: token);
String? token = await storage.read(key: "api_token");
```

### Request Headers

```
GET /api/auth/me HTTP/1.1
Host: localhost:8000
Authorization: Bearer 1|PZHueLvJEr6d9mU1d4J7FUVJiPh0LD1Uy6S2Qc
Content-Type: application/json
Accept: application/json
```

---

## Error Handling

### Typical HTTP Responses

| Status | Meaning | Action |
|--------|---------|--------|
| 200 | Success | Process response data |
| 201 | Created | Resource successfully created |
| 400 | Bad Request | Check request format/validation |
| 401 | Unauthorized | Token invalid/expired - re-login |
| 403 | Forbidden | User lacks permission for this action |
| 404 | Not Found | Resource doesn't exist |
| 500 | Server Error | Report to developer |

### Error Response Format
```json
{
  "success": false,
  "message": "Error description",
  "errors": {
    "field_name": ["Validation error message"]
  }
}
```

---

## Role-Based Permissions

| Feature | user | organizer | admin |
|---------|------|-----------|-------|
| View events | ✅ | ✅ | ✅ |
| Create event | ❌ | ✅ | ✅ |
| Edit own event | ❌ | ✅ | ✅ |
| Delete own event | ❌ | ✅ | ✅ |
| Manage favorites | ✅ | ✅ | ✅ |
| Admin panel | ❌ | ❌ | ✅ |

---

## Environment Details

- **Server**: http://localhost:8000
- **API Base**: http://localhost:8000/api
- **Database**: MySQL 5.7
- **Auth Method**: Laravel Sanctum (Personal Access Tokens)
- **Token Format**: UUID|plaintext_token

---

## Troubleshooting

### 401 Unauthorized
- Token might be expired
- Token format incorrect
- Token not included in header
- Solution: Re-login to get new token

### 403 Forbidden
- Your user role doesn't have permission
- Solution: Use appropriate user role for action

### 422 Unprocessable Entity
- Validation error in request data
- Check response `errors` field for details
- Ensure all required fields are provided

---

## Next Steps for Mobile Development

1. **Authentication Flow**
   - Create login screen with email/password fields
   - Implement token storage using platform-specific secure storage
   - Create auto-login using stored token

2. **Event Listing**
   - Fetch events from `/api/events`
   - Implement pagination if needed
   - Add search/filter functionality

3. **Event Details**
   - Show event location, description, contact info
   - Allow authenticated users to favorite events

4. **User Profile**
   - Display user info from `/api/auth/me`
   - Allow profile updates and password changes

5. **Event Management (for Organizers)**
   - Create events form
   - Edit/delete own events
   - View analytics

---

## Support & Documentation

- Laravel Sanctum Docs: https://laravel.com/docs/11.x/sanctum
- API Response Examples: See docs/API_RESPONSES.md
- Example Queries: See docs/EXAMPLE_QUERIES.php

---

**Last Updated**: April 2025
**Status**: ✅ Production Ready for Mobile App Development