# Relay Service

API gateway for Egregore.

## Purpose

Provides authenticated programmatic API access for external clients (mobile apps, integrations). Relays requests to backend services after validating JWT tokens.

## Endpoints

### Public
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Health check with backend status |
| `/auth/token` | POST | Exchange API key for JWT |

### Protected (requires JWT)
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/chat` | POST | Send message, get AI response |
| `/v1/history` | GET | Get message history |
| `/v1/history/search` | GET | Search messages |
| `/v1/tools` | GET | List available AI tools |

### Admin
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/admin/clients` | GET/POST | List or create API clients |
| `/admin/clients/{id}` | GET/PATCH/DELETE | Manage a client |
| `/admin/clients/{id}/regenerate-key` | POST | Regenerate API key |

## Authentication Flow

1. Create API client via admin endpoint
2. Client exchanges API key for JWT via `/auth/token`
3. JWT used in `Authorization: Bearer <token>` header
4. Tokens expire after 1 hour (configurable)

## Configuration

Environment variables (from `~/.env`):

| Variable | Description | Default |
|----------|-------------|---------|
| `JWT_SECRET` | Token signing secret | Auto-generated |
| `JWT_EXPIRY` | Token lifetime (seconds) | `3600` |
| `DATABASE_URL` | PostgreSQL for API clients | Standard connection |

## Running

```bash
# Activate venv
source ~/.venv/bin/activate

# Run directly
python main.py

# Or via systemd
sudo systemctl start relay
sudo systemctl status relay
```

## Rate Limiting

- General: 100 requests per client bucket
- `/v1/chat`: 10/minute (Claude API costs)

## Dependencies

- FastAPI
- PyJWT (token handling)
- bcrypt (key hashing)
- asyncpg (PostgreSQL)
- slowapi (rate limiting)