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

cd portal-server
cp .env.example .env

2. Edit Your .env File

Open .env in your editor and replace the placeholder values:

# 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

cargo run -- --from-env --verbose

4. Test API Access

# 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:

# ✅ 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:

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)

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

Production Setup

• Requires all security configurations
• Restricted CORS origins
• API keys are mandatory

# 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:

API_KEYS=dev_key_123,test_key_456

For Production

Use strong, random keys:

API_KEYS=prod_a1b2c3d4e5f6,prod_x9y8z7w6v5u4,prod_m3n4o5p6q7r8

Multiple Keys

You can configure multiple API keys for different clients:

API_KEYS=frontend_key_123,mobile_app_456,admin_panel_789

Integration Examples

Frontend 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

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

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.