75 lines
1.9 KiB
Markdown
75 lines
1.9 KiB
Markdown
|
# 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)
|