# Face Platform API Endpoints

## Admin Endpoints (No Authentication)

### Create Client
```
POST /api/admin/clients
Body: {"name": "Client Name"}
Response: Client with API key (visible once)
```

### List Clients
```
GET /api/admin/clients
Response: Array of clients (API keys hidden)
```

### Update Client Status
```
PATCH /api/admin/clients/{id}/status
Body: {"is_active": true|false}
Response: Updated client
```

## Face API Endpoints (API Key Required)

### Register Face
```
POST /api/face/register
Headers: X-API-KEY: face_xxx
Body: {"reference_id": "user_123", "image": "base64..."}
Response: Python service response (unchanged)
```

### Verify Face
```
POST /api/face/verify
Headers: X-API-KEY: face_xxx
Body: {"reference_id": "user_123", "image": "base64..."}
Response: Python service response (unchanged)
```

## Architecture

```
┌─────────┐                    ┌─────────┐                    ┌────────────┐
│ Client  │ ─── API Key ────> │ Laravel │ ─── Internal ────> │   Python   │
│         │                    │   API   │      Key           │   Engine   │
└─────────┘                    └─────────┘                    └────────────┘
                                    │
                                    ├─ Validate API Key
                                    ├─ Validate Payload
                                    ├─ Forward Request
                                    └─ Return Response
```

## Request Flow

1. **Client Authentication**
   - Client includes `X-API-KEY` header
   - Middleware validates against `clients` table
   - Only active clients allowed

2. **Request Validation**
   - Controller validates required fields
   - Returns 422 if validation fails

3. **Proxy to Python**
   - Service forwards request to Python engine
   - Includes internal `FACE_ENGINE_API_KEY`
   - Handles connection errors (503)

4. **Response**
   - Python response returned unchanged
   - Status code preserved
   - No data transformation

## Error Codes

| Code | Meaning | Source |
|------|---------|--------|
| 401 | Invalid/missing API key | Laravel Middleware |
| 422 | Validation error | Laravel Controller |
| 503 | Python engine unavailable | Laravel Service |
| 4xx/5xx | Python errors | Python Engine (forwarded) |

## Security

### Client API Keys
- Generated: `face_` + 40 random characters
- Stored: `clients` table (hashed in production)
- Exposed: Only on creation
- Validated: Every request

### Internal Credentials
- `FACE_ENGINE_URL`: Python service URL
- `FACE_ENGINE_API_KEY`: Internal authentication
- Storage: `.env` file only
- Exposure: Never to clients

### Data Handling
- ❌ Images NOT stored in Laravel
- ❌ Embeddings NOT stored in Laravel
- ❌ Face data NOT logged
- ✅ All face data in Python engine only

## Quick Start

```bash
# 1. Create client
curl -X POST http://localhost:8000/api/admin/clients \
  -H "Content-Type: application/json" \
  -d '{"name":"My App"}'

# Save the API key from response

# 2. Register a face
curl -X POST http://localhost:8000/api/face/register \
  -H "X-API-KEY: face_xxx" \
  -H "Content-Type: application/json" \
  -d '{"reference_id":"user_1","image":"base64..."}'

# 3. Verify a face
curl -X POST http://localhost:8000/api/face/verify \
  -H "X-API-KEY: face_xxx" \
  -H "Content-Type: application/json" \
  -d '{"reference_id":"user_1","image":"base64..."}'
```

## Documentation

- `docs/CLIENT_API.md` - Client management
- `docs/API_KEY_AUTH.md` - Authentication
- `docs/FACE_REGISTER_API.md` - Face registration
- `docs/FACE_VERIFY_API.md` - Face verification
- `docs/TESTING.md` - Integration tests
- `docs/SECURITY.md` - Security guidelines
- `docs/IMPLEMENTATION.md` - Technical details