Salon/docs/runbooks/auth_otp_failures.md

Runbook: Auth OTP Failures

Symptoms

• Users do not receive OTP.
• /api/auth/otp/request or /api/auth/phone/request fails.
• /api/auth/otp/verify or /api/auth/phone/verify shows invalid/expired unexpectedly.

Impact

Users cannot sign in/verify phone; booking/payment flows may block.

Quick Checks

• Confirm OTP_PROVIDER in backend/salon_api/settings.py.
• Check OTP provider credentials in backend/.env.
• Check app logs for provider/timeouts/rate-limit errors.
• Validate OTP rate-limit settings:
  • OTP_MAX_PER_WINDOW
  • OTP_WINDOW_MINUTES
  • OTP_RESEND_COOLDOWN_SECONDS
  • PHONE_AUTH_IP_MAX_PER_WINDOW
  • PHONE_AUTH_DEVICE_MAX_PER_WINDOW

Mitigation

1. Fix env/config mismatch; restart API.
2. If provider outage, use console only in non-prod.
3. If abuse spike/false positives, tune IP/device thresholds.
4. Verify server clock and OTP_EXPIRY_MINUTES.

Escalation

• Roll back recent auth changes if correlated with deployment.
• Escalate to Authentica with request IDs + timestamps.

References

• OTP logic: backend/apps/accounts/services/otp.py
• Risks: docs/risks.md