SMS Two-Factor Authentication Requirements

Overview

CODITECT supports SMS-based 2FA as an alternative to authenticator apps. This document outlines the requirements for enabling SMS verification.

Provider: Twilio (Recommended)

Twilio is the recommended SMS provider for production use.

Setup Steps

1. Create Twilio Account

   • Sign up at https://www.twilio.com/
   • Verify your email and phone number

2. Get Credentials

   • Navigate to Console Dashboard
   • Copy your Account SID and Auth Token
   • Purchase a phone number (or use trial number for testing)

3. Configure Environment Variables

   # Add to your .env or Secret Manager
   TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   TWILIO_AUTH_TOKEN=your_auth_token_here
   TWILIO_PHONE_NUMBER=+15551234567

4. Install Twilio SDK

   pip install twilio

   Or add to requirements.txt:

   twilio==8.13.0

GCP Secret Manager Setup

For production, store credentials in Secret Manager:

# Create secrets
echo -n "ACxxxxxxxxxx" | gcloud secrets create twilio-account-sid --data-file=-
echo -n "your_auth_token" | gcloud secrets create twilio-auth-token --data-file=-
echo -n "+15551234567" | gcloud secrets create twilio-phone-number --data-file=-

# Grant access to GKE service account
for secret in twilio-account-sid twilio-auth-token twilio-phone-number; do
  gcloud secrets add-iam-policy-binding $secret \
    --member="serviceAccount:django-backend@coditect-citus-prod.iam.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"
done

Kubernetes Deployment

Update your deployment to include Twilio secrets:

env:
  - name: TWILIO_ACCOUNT_SID
    valueFrom:
      secretKeyRef:
        name: twilio-credentials
        key: account-sid
  - name: TWILIO_AUTH_TOKEN
    valueFrom:
      secretKeyRef:
        name: twilio-credentials
        key: auth-token
  - name: TWILIO_PHONE_NUMBER
    valueFrom:
      secretKeyRef:
        name: twilio-credentials
        key: phone-number

Cost Estimates

Region	Cost per SMS
USA/Canada	$0.0079
UK	$0.0420
Germany	$0.0720
Australia	$0.0520

Monthly estimates (1,000 users, 2 SMS/user/month):

• USA: ~$16/month
• International mix: ~$50-100/month

Development Mode

When Twilio is not configured, the 2FA endpoints will:

1. Return warning in the response with the actual code
2. Allow testing without SMS delivery
3. Log that SMS service is not configured

Example response in development:

{
  "method": "sms",
  "phone_number_masked": "+1****7890",
  "warning": "SMS service not configured. For development, use code: 123456"
}

API Endpoints

Endpoint	Method	Description
/api/v1/auth/2fa/setup/	POST	Initialize SMS 2FA with phone number
/api/v1/auth/2fa/send-sms/	POST	Resend SMS verification code
/api/v1/auth/2fa/verify/	POST	Verify code and enable 2FA

Setup SMS 2FA

curl -X POST https://api.coditect.ai/api/v1/auth/2fa/setup/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"method": "sms", "phone_number": "+14155551234"}'

Verify Code

curl -X POST https://api.coditect.ai/api/v1/auth/2fa/verify/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

Security Considerations

1. Rate Limiting: Implement rate limiting on SMS endpoints (max 5/hour)
2. Code Expiry: SMS codes expire after 5 minutes (300 seconds)
3. Phone Verification: Consider verifying phone ownership before enabling
4. Backup Codes: Always provide backup codes when enabling 2FA
5. Audit Logging: Log all 2FA setup/disable events

Alternatives to Twilio

Provider	Pros	Cons
AWS SNS	Good if already on AWS	Requires AWS setup
Vonage (Nexmo)	Competitive pricing	Less documentation
MessageBird	EU-focused	Smaller market presence
Plivo	Lower cost	Fewer features

Testing

Run 2FA tests:

pytest tests/test_2fa.py -v

Troubleshooting

SMS not delivered

1. Check Twilio console for delivery status
2. Verify phone number format (E.164: +14155551234)
3. Check account balance
4. Review Twilio error codes in logs

Invalid code errors

1. Verify time synchronization (TOTP is time-based)
2. Check code expiry (5 minutes for SMS)
3. Ensure correct code entry (no spaces)

---

Last Updated: January 2, 2026 Author: CODITECT Development Team