relay/README.md

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

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