campaign_connector/docs/security/api-security.md

# API Security

This document covers the API authentication implementation in SMS Campaign Manager.

## Authentication System

All API endpoints require authentication via one of:

- **X-API-Key header**: `X-API-Key: YOUR_KEY`
- **Bearer token**: `Authorization: Bearer YOUR_KEY`
- **Session cookie**: From web login

## API Key Types

| Key | Variable | Access Level |
|-----|----------|--------------|
| Admin | `ADMIN_API_KEY` | Full access including database reset |
| User | `USER_API_KEY` | Standard operations |
| Termux | `TERMUX_API_KEY` | Android device communication |

### Admin Key

Use for administrative operations:

- All user permissions
- `/api/database/reset` - Database reset
- System configuration changes

### User Key

Use for standard operations:

- Campaign management
- SMS sending
- CSV upload
- Analytics viewing

### Termux Key

Use for Android communication:

- Internal server-to-device requests
- SMS sending via Termux API
- Device status queries

## Protected Endpoints

### Campaign Routes

All require User role minimum:

- `POST /api/campaign/create`
- `POST /api/campaign/start`
- `POST /api/campaign/pause`
- `POST /api/campaign/resume`
- `GET /api/campaign/status`
- `GET /api/campaign/list`

### SMS Routes

All require User role minimum:

- `POST /api/sms/send/enhanced`
- `POST /api/sms/test`
- `GET /api/sms/status`

### Upload Routes

All require User role minimum:

- `POST /api/csv/upload`
- `POST /api/campaign/upload`

### Database Routes

- `GET /api/database/stats` - User role
- `POST /api/database/reset` - Admin role only

### Android Termux API

Protected endpoints on Android:

- `POST /api/sms/send`
- `POST /api/sms/send-reply`

## Security Features

### Key Hashing

API keys are hashed with SHA-256 before comparison. Keys are never stored in plaintext.

### Constant-Time Comparison

All key comparisons use constant-time algorithms to prevent timing attacks.

### Role-Based Access

Each endpoint declares required role level:

```python
@require_auth(role='admin')  # Admin only
@require_auth(role='user')   # User or Admin
```

## Generating Keys

Generate new API keys:

```bash
python3 src/core/auth.py
```

This generates cryptographically secure 64-character hex strings.

## Using API Keys

### curl Examples

```bash
# X-API-Key header
curl -H "X-API-Key: YOUR_KEY" http://localhost:5000/api/campaign/list

# Bearer token
curl -H "Authorization: Bearer YOUR_KEY" http://localhost:5000/api/campaign/list

# POST with data
curl -X POST \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+1234567890","message":"Hello"}' \
  http://localhost:5000/api/sms/send/enhanced
```

### Python Example

```python
import requests

API_KEY = "your-api-key-here"
BASE_URL = "http://localhost:5000"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# List campaigns
response = requests.get(f"{BASE_URL}/api/campaign/list", headers=headers)
print(response.json())

# Send SMS
data = {"phone": "+1234567890", "message": "Test"}
response = requests.post(f"{BASE_URL}/api/sms/send/enhanced", headers=headers, json=data)
print(response.json())
```

## Error Responses

### 401 Unauthorized

No API key or invalid key:

```json
{
  "error": "Authentication required",
  "message": "Please provide valid API key"
}
```

### 403 Forbidden

Valid key but insufficient permissions:

```json
{
  "error": "Insufficient permissions",
  "message": "Admin role required"
}
```

## Best Practices

### Required

- Generate unique random keys
- Store keys in `.env` file only
- Set file permissions: `chmod 600 .env`
- Never commit keys to version control

### Recommended

- Rotate keys every 90 days
- Use different keys per environment
- Monitor failed authentication logs
- Use HTTPS in production (Tailscale provides this)

## Troubleshooting

### Invalid API Key

```bash
# Verify key is set in container
docker compose exec sms-campaign env | grep API_KEY

# Check .env format (no spaces around =)
cat .env | grep API_KEY

# Restart to reload
docker compose restart
```

### Permission Denied

Using wrong key type for endpoint:

- User key for admin endpoints returns 403
- Check endpoint requires admin role
- Use admin key for privileged operations

## Related Documentation

- [Security Setup](security-setup.md) - Complete security configuration
- [Authentication Setup](../setup/authentication.md) - User login
- [API Endpoints](../api/endpoints.md) - Full endpoint reference
- [Environment Variables](../reference/environment-variables.md) - Configuration