perling/docs/authentication.md

# Authentication System Documentation

## Overview

The application uses a dual authentication system:

-   **Web Authentication**: Session-based with cookies for browser access
-   **API Authentication**: Token-based using Laravel Sanctum for API access

## Web Authentication (Session + Cookies)

### Login

**Endpoint**: `POST /auth/session-login`
**Controller**: `WebAuthController@sessionLogin`

```bash
curl -X POST http://localhost:8000/auth/session-login \
  -H "Content-Type: application/json" \
  -H "X-CSRF-TOKEN: your-csrf-token" \
  -d '{
    "identifier": "user@example.com",
    "password": "password123"
  }'
```

**Response**:

```json
{
    "success": true,
    "message": "Login berhasil",
    "user": {
        "id": 1,
        "name": "John Doe",
        "email": "user@example.com",
        "username": "johndoe"
    }
}
```

### Logout

**Endpoint**: `POST /auth/logout`
**Controller**: `WebAuthController@sessionLogout`

```bash
curl -X POST http://localhost:8000/auth/logout \
  -H "Content-Type: application/json" \
  -H "X-CSRF-TOKEN: your-csrf-token"
```

### Protected Routes

All admin routes are protected with `web.auth` middleware:

-   `/dashboard/*`
-   `/admin/*`

## API Authentication (Token-based)

### Login

**Endpoint**: `POST /api/auth/login`
**Controller**: `AuthController@login`

```bash
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "user@example.com",
    "password": "password123",
    "device_name": "mobile-app"
  }'
```

**Response**:

```json
{
    "success": true,
    "message": "Login berhasil",
    "token": "1|abc123def456...",
    "token_type": "Bearer",
    "user": {
        "id": 1,
        "name": "John Doe",
        "email": "user@example.com",
        "username": "johndoe",
        "roles": ["admin"],
        "permissions": ["dashboard.view", "settings.manage"]
    }
}
```

### Using API Token

Include the token in the Authorization header:

```bash
curl -X GET http://localhost:8000/api/auth/me \
  -H "Authorization: Bearer 1|abc123def456..."
```

### Get User Info

**Endpoint**: `GET /api/auth/me`

```bash
curl -X GET http://localhost:8000/api/auth/me \
  -H "Authorization: Bearer your-token"
```

### Logout (Current Device)

**Endpoint**: `POST /api/auth/logout`

```bash
curl -X POST http://localhost:8000/api/auth/logout \
  -H "Authorization: Bearer your-token"
```

### Logout All Devices

**Endpoint**: `POST /api/auth/logout-all`

```bash
curl -X POST http://localhost:8000/api/auth/logout-all \
  -H "Authorization: Bearer your-token"
```

## Configuration

### Guards

-   `web`: Session-based authentication for web interface
-   `sanctum`: Token-based authentication for API

### Middleware

-   `web.auth`: Custom middleware for web session authentication
-   `auth:sanctum`: Laravel Sanctum middleware for API authentication

### Token Management

-   Tokens are device-specific (one token per device)
-   Old tokens for the same device are automatically revoked on new login
-   Tokens don't expire by default (configurable in sanctum config)

## Security Features

### Web Authentication

-   CSRF protection enabled
-   Session regeneration on login
-   Remember token invalidation on logout
-   Cookie cleanup on logout

### API Authentication

-   Device-specific tokens
-   Token revocation on logout
-   Automatic cleanup of old tokens
-   Rate limiting (configurable)

## Error Handling

### Common Error Responses

**Invalid Credentials**:

```json
{
    "message": "The given data was invalid.",
    "errors": {
        "identifier": ["Email/username atau password yang diberikan salah."]
    }
}
```

**Unauthenticated**:

```json
{
    "success": false,
    "message": "Unauthenticated"
}
```

## Testing

### Web Authentication Test

```bash
# Login
curl -c cookies.txt -X POST http://localhost:8000/auth/session-login \
  -H "Content-Type: application/json" \
  -d '{"identifier": "admin@example.com", "password": "password"}'

# Access protected route
curl -b cookies.txt http://localhost:8000/dashboard

# Logout
curl -b cookies.txt -X POST http://localhost:8000/auth/logout
```

### API Authentication Test

```bash
# Login and save token
TOKEN=$(curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"identifier": "admin@example.com", "password": "password"}' \
  | jq -r '.token')

# Use token
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/auth/me

# Logout
curl -X POST http://localhost:8000/api/auth/logout \
  -H "Authorization: Bearer $TOKEN"
```