feat: Complete API authentication system with email & Telegram support
- Add email/password registration endpoint (/api/v1/auth/register) - Add JWT token endpoints for Telegram users (/api/v1/auth/token/get, /api/v1/auth/token/refresh-telegram) - Enhance User model to support both email and Telegram authentication - Fix JWT token handling: convert sub to string (RFC compliance with PyJWT 2.10.1+) - Fix bot API calls: filter None values from query parameters - Fix JWT extraction from Redis: handle both bytes and string returns - Add public endpoints to JWT middleware: /api/v1/auth/register, /api/v1/auth/token/* - Update bot commands: /register (one-tap), /link (account linking), /start (options) - Create complete database schema migration with email auth support - Remove deprecated version attribute from docker-compose.yml - Add service dependency: bot waits for web service startup Features: - Dual authentication: email/password OR Telegram ID - JWT tokens with 15-min access + 30-day refresh lifetime - Redis-based token storage with TTL - Comprehensive API documentation and integration guides - Test scripts and Python examples - Full deployment checklist Database changes: - User model: added email, password_hash, email_verified (nullable fields) - telegram_id now nullable to support email-only users - Complete schema with families, accounts, categories, transactions, budgets, goals Status: Production-ready with all tests passing
This commit is contained in:
257
API_QUICK_START.md
Normal file
257
API_QUICK_START.md
Normal file
@@ -0,0 +1,257 @@
|
||||
# Quick Start - Bot API Integration
|
||||
|
||||
## 🚀 Deploy in 5 Minutes
|
||||
|
||||
### 1. Apply Database Migration
|
||||
```bash
|
||||
docker compose down
|
||||
docker compose up -d
|
||||
docker exec finance_bot_migrations alembic upgrade head
|
||||
```
|
||||
|
||||
### 2. Rebuild Containers
|
||||
```bash
|
||||
docker compose down
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
### 3. Test API Endpoint
|
||||
```bash
|
||||
# Register new user
|
||||
curl -X POST http://localhost:8000/api/v1/auth/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email":"test@example.com","password":"test123","first_name":"Test"}'
|
||||
|
||||
# Expected: Returns access_token and user_id
|
||||
```
|
||||
|
||||
### 4. Test Bot /register Command
|
||||
```bash
|
||||
# Send /register to your Telegram bot
|
||||
# Expected: "Registration successful!" message
|
||||
```
|
||||
|
||||
### 5. Verify Token in Redis
|
||||
```bash
|
||||
docker exec finance_bot_redis redis-cli get "chat_id:YOURCHATID:jwt"
|
||||
# Expected: JWT token string
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 What Was Added
|
||||
|
||||
### New API Endpoints
|
||||
| Endpoint | Purpose |
|
||||
|----------|---------|
|
||||
| `POST /api/v1/auth/register` | Email registration |
|
||||
| `POST /api/v1/auth/token/get` | Get token by chat_id |
|
||||
| `POST /api/v1/auth/token/refresh-telegram` | Refresh Telegram token |
|
||||
| `POST /api/v1/auth/telegram/register` | Quick Telegram registration |
|
||||
|
||||
### New Bot Commands
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `/start` | Show registration options |
|
||||
| `/register` | One-tap Telegram registration |
|
||||
| `/link` | Link existing email account |
|
||||
| `/help` | Updated help with new options |
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Quick Tests
|
||||
|
||||
### Test 1: Email Registration
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/v1/auth/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"email": "user@example.com",
|
||||
"password": "SecurePass123",
|
||||
"first_name": "John"
|
||||
}'
|
||||
```
|
||||
|
||||
### Test 2: Telegram User Token
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/v1/auth/token/get \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"chat_id": 556399210}'
|
||||
```
|
||||
|
||||
### Test 3: Quick Telegram Register
|
||||
```bash
|
||||
curl -X POST "http://localhost:8000/api/v1/auth/telegram/register" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "" \
|
||||
-G \
|
||||
--data-urlencode "chat_id=556399210" \
|
||||
--data-urlencode "username=john_doe" \
|
||||
--data-urlencode "first_name=John"
|
||||
```
|
||||
|
||||
### Test 4: Health Check
|
||||
```bash
|
||||
curl http://localhost:8000/health
|
||||
# Expected: {"status": "ok", "environment": "production"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Authentication Flows
|
||||
|
||||
### Quick Telegram Registration (1 step)
|
||||
```
|
||||
User /register
|
||||
↓
|
||||
Bot → POST /api/v1/auth/telegram/register
|
||||
↓
|
||||
Bot ← JWT Token
|
||||
↓
|
||||
User ready to use!
|
||||
```
|
||||
|
||||
### Email Account Link (3 steps)
|
||||
```
|
||||
User /link
|
||||
↓
|
||||
Bot → POST /api/v1/auth/telegram/start (get code)
|
||||
↓
|
||||
User clicks link, logs in with email
|
||||
↓
|
||||
Frontend → POST /api/v1/auth/telegram/confirm
|
||||
↓
|
||||
Bot → POST /api/v1/auth/token/get
|
||||
↓
|
||||
User ready to use!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Full Documentation
|
||||
|
||||
1. **API Endpoints**: `docs/API_ENDPOINTS.md`
|
||||
2. **Integration Guide**: `docs/API_INTEGRATION_GUIDE.md`
|
||||
3. **Complete Summary**: `BOT_API_INTEGRATION_SUMMARY.md`
|
||||
4. **Deployment Checklist**: `DEPLOYMENT_CHECKLIST_API.md`
|
||||
5. **Python Examples**: `examples/bot_api_usage.py`
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Common Commands
|
||||
|
||||
### Check Logs
|
||||
```bash
|
||||
# Web service
|
||||
docker logs -f finance_bot_web
|
||||
|
||||
# Bot service
|
||||
docker logs -f finance_bot_bot
|
||||
|
||||
# Database
|
||||
docker logs -f finance_bot_postgres
|
||||
```
|
||||
|
||||
### Database Access
|
||||
```bash
|
||||
# List users
|
||||
docker exec finance_bot_postgres psql -U finance_user -d finance_db \
|
||||
-c "SELECT id, email, telegram_id, created_at FROM users"
|
||||
|
||||
# Check table structure
|
||||
docker exec finance_bot_postgres psql -U finance_user -d finance_db \
|
||||
-c "\d users"
|
||||
```
|
||||
|
||||
### Redis Access
|
||||
```bash
|
||||
# Check stored tokens
|
||||
docker exec finance_bot_redis redis-cli keys "chat_id:*:jwt"
|
||||
|
||||
# Get specific token
|
||||
docker exec finance_bot_redis redis-cli get "chat_id:556399210:jwt"
|
||||
|
||||
# Flush all (careful!)
|
||||
docker exec finance_bot_redis redis-cli FLUSHALL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Verification Checklist
|
||||
|
||||
- [ ] Database migration applied successfully
|
||||
- [ ] Email registration endpoint works
|
||||
- [ ] Telegram token endpoint works
|
||||
- [ ] Bot /register command works
|
||||
- [ ] Tokens stored in Redis
|
||||
- [ ] No errors in logs
|
||||
- [ ] Health check returns 200
|
||||
- [ ] Documentation accessible
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Troubleshooting
|
||||
|
||||
### Migration Failed
|
||||
```bash
|
||||
# Check migration status
|
||||
docker exec finance_bot_migrations alembic current
|
||||
|
||||
# Rollback
|
||||
docker exec finance_bot_migrations alembic downgrade -1
|
||||
|
||||
# Reapply
|
||||
docker exec finance_bot_migrations alembic upgrade head
|
||||
```
|
||||
|
||||
### Bot Can't Connect to Web
|
||||
```bash
|
||||
# Check network
|
||||
docker network ls
|
||||
docker network inspect finance_network
|
||||
|
||||
# Check web is running
|
||||
docker exec finance_bot_web curl localhost:8000/health
|
||||
```
|
||||
|
||||
### Tokens Not Storing in Redis
|
||||
```bash
|
||||
# Check Redis is running
|
||||
docker exec finance_bot_redis redis-cli ping
|
||||
|
||||
# Check connection string
|
||||
docker compose config | grep REDIS_URL
|
||||
```
|
||||
|
||||
### API Returns 500 Error
|
||||
```bash
|
||||
# Check web logs
|
||||
docker logs finance_bot_web | grep ERROR
|
||||
|
||||
# Restart web service
|
||||
docker restart finance_bot_web
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
**API Issues?**
|
||||
1. Check `docs/API_ENDPOINTS.md`
|
||||
2. Review logs: `docker logs finance_bot_web`
|
||||
3. Test with cURL first
|
||||
|
||||
**Bot Issues?**
|
||||
1. Check bot is running: `docker logs finance_bot_bot`
|
||||
2. Verify token storage: `redis-cli keys "chat_id:*:jwt"`
|
||||
3. Check API connection: `docker compose logs`
|
||||
|
||||
**Database Issues?**
|
||||
1. Check database is running: `docker exec finance_bot_postgres psql -U finance_user -d finance_db -c "SELECT 1"`
|
||||
2. Check migration status: `docker exec finance_bot_migrations alembic current`
|
||||
|
||||
---
|
||||
|
||||
**Status**: 🟢 Ready to Deploy
|
||||
|
||||
See `DEPLOYMENT_CHECKLIST_API.md` for full deployment steps.
|
||||
Reference in New Issue
Block a user