Fleshed out documentation

2026-02-28 17:41:00 +03:00
parent 828cbcc822
commit aa607b9b6e
13 changed files with 332 additions and 9 deletions
@@ -0,0 +1,39 @@
+# Runbook: Auth OTP Failures
+
+## Summary
+
+Guide for diagnosing and mitigating OTP send or verify failures in phone-first authentication.
+
+## Symptoms
+
+- Users report not receiving OTP codes.
+- `/api/auth/otp/request/` or `/api/auth/phone/request/` returns HTTP 500 or rate-limit errors.
+- `/api/auth/otp/verify/` or `/api/auth/phone/verify/` returns invalid or expired OTP errors unexpectedly.
+
+## Impact
+
+- Users cannot sign in or complete phone verification.
+- Booking and payment flows are blocked when auth is required.
+
+## Quick Checks
+
+- Confirm the provider configured in `backend/salon_api/settings.py` via `OTP_PROVIDER`.
+- Check recent application logs for OTP send errors.
+- Verify provider credentials are present in `backend/.env` for the active provider.
+
+## Mitigation Steps
+
+- If provider credentials are missing or invalid, fix the environment variables and restart the API process.
+- If the provider is down, temporarily switch to `OTP_PROVIDER=console` for non-production environments and notify support.
+- If rate limits are triggered, validate `OTP_MAX_PER_WINDOW`, `OTP_WINDOW_MINUTES`, and `OTP_RESEND_COOLDOWN_SECONDS` values and confirm client behavior is not retrying aggressively.
+- If verification is failing, confirm server time is correct and `OTP_EXPIRY_MINUTES` is appropriate.
+
+## Rollback / Escalation
+
+- Roll back recent auth/OTP changes if the failure coincides with a deployment.
+- Escalate to the provider (Authentica) with request IDs and timestamps if external API errors persist.
+
+## Notes
+
+- Authentica is the primary OTP provider for MVP; console provider is for local development.
+- OTP send/verify logic lives in `backend/apps/accounts/services/otp.py`.