# API Key Management - Quick Reference

## 🎯 The Big Picture

**Problem:** You want to develop locally with convenience, but alpha testers should use their own API keys (so you don't pay for their usage).

**Solution:** 
- **Local Dev**: API keys saved to `.env` files (convenient)
- **Production**: API keys saved to database per user (isolated, zero cost to you)

---

## 🚀 How It Works

### **1. Local Development (You)**

```bash
# backend/.env
DEBUG=true
GEMINI_API_KEY=your_key_here
EXA_API_KEY=your_exa_key
COPILOTKIT_API_KEY=your_copilot_key
```

**Behavior:**
- ✅ Complete onboarding once
- ✅ Keys saved to `.env` AND database
- ✅ All services use keys from `.env`
- ✅ Convenient, keys persist

**You pay for:** Your own API usage

---

### **2. Production (Alpha Testers)**

```bash
# Render environment variables
DEBUG=false
DEPLOY_ENV=render
DATABASE_URL=postgresql://...
```

**Behavior:**
- ✅ Each tester completes onboarding with their keys
- ✅ Keys saved to database (user-specific rows)
- ✅ Services fetch keys from database per user
- ✅ Complete user isolation

**You pay for:** $0-$7/month (infrastructure only)  
**Testers pay for:** Their own API usage

---

## 📝 Code Examples

### **Using User API Keys in Services**

```python
from services.user_api_key_context import user_api_keys
import google.generativeai as genai

def generate_blog(user_id: str, topic: str):
    # Get user-specific API keys
    with user_api_keys(user_id) as keys:
        gemini_key = keys.get('gemini')
        
        # Configure Gemini with THIS user's key
        genai.configure(api_key=gemini_key)
        model = genai.GenerativeModel('gemini-pro')
        
        # Generate content (charges THIS user's Gemini account)
        response = model.generate_content(f"Write a blog about {topic}")
        return response.text
```

**What this does:**
- **Dev mode** (`user_id=None` or `DEBUG=true`): Uses `.env` file
- **Prod mode** (`DEPLOY_ENV=render`): Fetches from database for this `user_id`

---

## 🔄 Migration Checklist

### **Step 1: Update Environment Variables**

**Local (backend/.env):**
```bash
DEBUG=true
# Your development API keys (stay as-is)
GEMINI_API_KEY=...
EXA_API_KEY=...
```

**Render Dashboard:**
```bash
DEBUG=false
DEPLOY_ENV=render
DATABASE_URL=postgresql://...
# Remove GEMINI_API_KEY, EXA_API_KEY from here!
# Users will provide their own via onboarding
```

### **Step 2: Update Services to Use user_api_keys**

**Before:**
```python
import os
gemini_key = os.getenv('GEMINI_API_KEY')  # ❌ Same for all users!
```

**After:**
```python
from services.user_api_key_context import user_api_keys
with user_api_keys(user_id) as keys:
    gemini_key = keys.get('gemini')  # ✅ User-specific!
```

### **Step 3: Update FastAPI Endpoints**

**Add user_id parameter:**
```python
@router.post("/api/generate")
async def generate(
    prompt: str,
    current_user: dict = Depends(get_current_user)  # Get authenticated user
):
    user_id = current_user.get('user_id')  # Extract user_id
    
    # Pass user_id to service
    result = await my_service.generate(user_id, prompt)
    return result
```

### **Step 4: Test**

**Local:**
1. Complete onboarding
2. Check `backend/.env` has your keys ✅
3. Generate content - should work ✅

**Production:**
1. Deploy to Render with `DEPLOY_ENV=render`
2. User A: Complete onboarding with keys A
3. User B: Complete onboarding with keys B
4. User A generates content → Uses keys A ✅
5. User B generates content → Uses keys B ✅

---

## 🔍 Troubleshooting

### **"No API key found" error**

**In development:**
```bash
# Check backend/.env exists and has:
DEBUG=true
GEMINI_API_KEY=your_key_here
```

**In production:**
```sql
-- Check database has keys for this user:
SELECT s.user_id, k.provider, k.key
FROM api_keys k
JOIN onboarding_sessions s ON k.session_id = s.id
WHERE s.user_id = 'user_xxx';
```

### **Wrong user's keys being used**

**Cause:** Service not using `user_api_keys(user_id)`

**Fix:**
```python
# OLD (wrong):
gemini_key = os.getenv('GEMINI_API_KEY')

# NEW (correct):
with user_api_keys(user_id) as keys:
    gemini_key = keys.get('gemini')
```

### **Keys not saving to .env in development**

**Cause:** `DEBUG` not set to `true`

**Fix:**
```bash
# backend/.env
DEBUG=true  # Must be explicitly true
```

---

## 📊 Cost Breakdown

### **Your Monthly Costs**

| Item | Dev | Production |
|------|-----|------------|
| **Infrastructure** | $0 | $0-7/month |
| **Database** | Free | Free (Render) |
| **API Usage (Gemini, Exa, etc.)** | Your usage | $0 (users pay!) |
| **Total** | Your API usage | $0-7/month |

### **Alpha Tester Costs**

| Item | Cost |
|------|------|
| **ALwrity Subscription** | Free (alpha) |
| **Their Gemini API** | Their usage |
| **Their Exa API** | Their usage |
| **Total** | Their API usage |

---

## 🎓 Key Concepts

### **Environment Detection**

```python
is_development = (
    os.getenv('DEBUG', 'false').lower() == 'true' or
    os.getenv('DEPLOY_ENV') is None
)

if is_development:
    # Use .env file (convenience)
    keys = load_from_env()
else:
    # Use database (user isolation)
    keys = load_from_database(user_id)
```

### **User Isolation**

```
Database guarantees:
┌──────────────────┬─────────────┬──────────────────┐
│ user_id          │ provider    │ key              │
├──────────────────┼─────────────┼──────────────────┤
│ user_tester_a    │ gemini      │ tester_a_key     │ ← Isolated
│ user_tester_b    │ gemini      │ tester_b_key     │ ← Isolated
└──────────────────┴─────────────┴──────────────────┘

Query for Tester A: WHERE user_id = 'user_tester_a'
Query for Tester B: WHERE user_id = 'user_tester_b'

No overlap, no conflicts!
```

---

## 🚀 Quick Start

### **For Local Development:**

1. Clone repo
2. Set `DEBUG=true` in `backend/.env`
3. Add your API keys to `backend/.env`
4. Run backend: `python start_alwrity_backend.py --dev`
5. Complete onboarding (keys auto-save to `.env`)
6. Done! ✅

### **For Production Deployment:**

1. Deploy backend to Render
2. Set environment variables:
   - `DEBUG=false`
   - `DEPLOY_ENV=render`
   - `DATABASE_URL=postgresql://...`
3. Deploy frontend to Vercel
4. Alpha testers complete onboarding with their keys
5. Done! Each tester uses their own keys ✅

---

## 📚 Further Reading

- [Complete Architecture Guide](./API_KEY_MANAGEMENT_ARCHITECTURE.md)
- [Usage Examples](./EXAMPLES_USER_API_KEYS.md)
- [Flow Diagrams](./API_KEY_FLOW_DIAGRAM.md)

---

## ✅ Summary

**The magic:**
- Same codebase works in both dev and prod
- Dev: Convenience of `.env` files
- Prod: Isolation via database
- Zero cost: Testers use their own API keys
- Automatic: Just set `DEBUG` and `DEPLOY_ENV`

**Bottom line:**
> Write code once, works everywhere. Development is convenient, production is isolated. You focus on building, testers pay for their usage. Win-win! 🎉