freezone/portal-server/SETUP.md

# Portal Server Setup Guide

This guide will help you set up the portal-server quickly and resolve common 401 authentication errors.

## Quick Setup (5 minutes)

### 1. Copy Environment File
```bash
cd portal-server
cp .env.example .env
```

### 2. Edit Your .env File
Open `.env` in your editor and replace the placeholder values:

```bash
# Required: Replace with your actual Stripe keys
STRIPE_SECRET_KEY=sk_test_your_actual_stripe_secret_key_here
STRIPE_PUBLISHABLE_KEY=pk_test_your_actual_stripe_publishable_key_here

# Required: Replace with your actual Identify API key
IDENTIFY_API_KEY=your_actual_identify_api_key_here

# Required: Set API keys for authentication (prevents 401 errors)
API_KEYS=dev_key_123,another_key_456

# Optional: Webhook secrets (for production)
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
IDENTIFY_WEBHOOK_SECRET=your_identify_webhook_secret_here
```

### 3. Start the Server
```bash
cargo run -- --from-env --verbose
```

### 4. Test API Access
```bash
# This should work (replace dev_key_123 with your actual API key)
curl -X GET http://localhost:3001/api/health \
  -H "x-api-key: dev_key_123"

# This will return 401 Unauthorized (no API key)
curl -X GET http://localhost:3001/api/health
```

## Troubleshooting

### Getting 401 Unauthorized Errors?

**Problem**: All API calls return `401 Unauthorized`

**Solution**: Make sure you include the `x-api-key` header in all requests:

```bash
# ✅ Correct - includes API key header
curl -X POST http://localhost:3001/api/kyc/create-verification-session \
  -H "Content-Type: application/json" \
  -H "x-api-key: dev_key_123" \
  -d '{"user_id": "test123", "email": "test@example.com"}'

# ❌ Wrong - missing API key header
curl -X POST http://localhost:3001/api/kyc/create-verification-session \
  -H "Content-Type: application/json" \
  -d '{"user_id": "test123", "email": "test@example.com"}'
```

### Server Won't Start?

**Problem**: Server fails to start with environment variable errors

**Solutions**:
1. Check that your `.env` file exists: `ls -la .env`
2. Verify all required variables are set: `cat .env`
3. Make sure API keys are valid (no extra spaces or quotes)

### Can't Find .env File?

The server looks for `.env` files in this order:
1. `.env` (current directory)
2. `portal-server/.env` (if running from parent directory)

You can also specify a custom location:
```bash
cargo run -- --from-env --env-file /path/to/your/.env
```

## Development vs Production

### Development Setup (Default)
- Uses `.env` file for configuration
- Allows all CORS origins (`*`)
- API keys are optional (but recommended)

```bash
# Development mode
cargo run -- --from-env --verbose
```

### Production Setup
- Requires all security configurations
- Restricted CORS origins
- API keys are mandatory

```bash
# Production build
cargo build --release --features prod --no-default-features

# Production run
./target/release/portal-server --from-env --cors-origins "https://yourdomain.com"
```

## API Key Management

### For Development
Use simple, memorable keys in your `.env`:
```bash
API_KEYS=dev_key_123,test_key_456
```

### For Production
Use strong, random keys:
```bash
API_KEYS=prod_a1b2c3d4e5f6,prod_x9y8z7w6v5u4,prod_m3n4o5p6q7r8
```

### Multiple Keys
You can configure multiple API keys for different clients:
```bash
API_KEYS=frontend_key_123,mobile_app_456,admin_panel_789
```

## Integration Examples

### Frontend JavaScript
```javascript
const apiKey = 'dev_key_123'; // From your .env API_KEYS

const response = await fetch('http://localhost:3001/api/kyc/create-verification-session', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': apiKey
  },
  body: JSON.stringify({
    user_id: 'user123',
    email: 'user@example.com'
  })
});
```

### Python
```python
import requests

api_key = 'dev_key_123'  # From your .env API_KEYS

response = requests.post(
    'http://localhost:3001/api/kyc/create-verification-session',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': api_key
    },
    json={
        'user_id': 'user123',
        'email': 'user@example.com'
    }
)
```

### Rust
```rust
use reqwest::Client;
use serde_json::json;

let client = Client::new();
let api_key = "dev_key_123"; // From your .env API_KEYS

let response = client
    .post("http://localhost:3001/api/kyc/create-verification-session")
    .header("Content-Type", "application/json")
    .header("x-api-key", api_key)
    .json(&json!({
        "user_id": "user123",
        "email": "user@example.com"
    }))
    .send()
    .await?;
```

## Next Steps

1. **Set up webhooks**: Configure `STRIPE_WEBHOOK_SECRET` and `IDENTIFY_WEBHOOK_SECRET` for production
2. **Configure CORS**: Set specific origins for production: `CORS_ORIGINS=https://yourdomain.com`
3. **Add rate limiting**: Consider implementing rate limiting for production use
4. **Monitor logs**: Use `--verbose` flag to see detailed request logs

For more details, see the main [README.md](README.md).