Getting Started

Getting Started#

This guide will walk you through installing and configuring django-phone-verify in your Django project. By the end, you’ll have a working phone verification system ready to use.

Prerequisites#

Before you begin, make sure you have:

  • Python 3.8+ installed

  • Django 2.1+ in your project

  • Django REST Framework 3.9+ (if using the API viewsets)

  • An account with Twilio or Nexmo/Vonage (for sending SMS in production)

Installation#

You can install django-phone-verify using pip. The package supports optional extras for different SMS backends:

# Install with Twilio support (recommended for most users)
pip install django-phone-verify[twilio]

# Or install with Nexmo/Vonage support
pip install django-phone-verify[nexmo]

# Install with all supported backends
pip install django-phone-verify[all]

# Core only (if you're writing a custom backend)
pip install django-phone-verify

Note

We recommend installing with [twilio] or [nexmo] extras to ensure all required dependencies are installed for your chosen SMS provider.

Configuration#

Follow these steps to configure django-phone-verify in your Django project:

Step 1: Add to INSTALLED_APPS#

Add phone_verify to your INSTALLED_APPS in settings.py:

# settings.py

INSTALLED_APPS = [
    ...
    'phone_verify',
    ...
]

Step 2: Run Migrations#

Create the necessary database tables:

python manage.py migrate

This creates the SMSVerification table to store phone numbers, session tokens, and security codes.

Step 3: Add URLs (if using DRF API)#

Include the phone verification URLs in your project’s urls.py:

# urls.py
from django.urls import path, include

urlpatterns = [
    ...
    path('api/phone/', include('phone_verify.urls')),
    ...
]

This provides the /api/phone/register/ and /api/phone/verify/ endpoints.

Step 4: Configure PHONE_VERIFICATION Settings#

Add the PHONE_VERIFICATION configuration to your settings.py.

For Twilio:

# settings.py
import os

PHONE_VERIFICATION = {
    'BACKEND': 'phone_verify.backends.twilio.TwilioBackend',
    'OPTIONS': {
        'SID': os.environ.get('TWILIO_ACCOUNT_SID'),      # Your Twilio Account SID
        'SECRET': os.environ.get('TWILIO_AUTH_TOKEN'),    # Your Twilio Auth Token
        'FROM': os.environ.get('TWILIO_PHONE_NUMBER'),    # Your Twilio phone number (e.g., '+1234567890')
    },
    'TOKEN_LENGTH': 6,                                     # Length of security code
    'MIN_TOKEN_LENGTH': 6,                                 # Minimum allowed token length for security
    'MAX_FAILED_ATTEMPTS': 5,                             # Maximum failed verification attempts before locking session
    'MESSAGE': 'Welcome to {app}! Please use security code {security_code} to proceed.',
    'APP_NAME': 'MyApp',                                   # Your app name (used in MESSAGE)
    'SECURITY_CODE_EXPIRATION_SECONDS': 600,                 # 10 minutes (in seconds)
    'VERIFY_SECURITY_CODE_ONLY_ONCE': True,               # Code can only be used once
}

For Nexmo/Vonage:

# settings.py
import os

PHONE_VERIFICATION = {
    'BACKEND': 'phone_verify.backends.nexmo.NexmoBackend',
    'OPTIONS': {
        'KEY': os.environ.get('NEXMO_API_KEY'),           # Your Nexmo API Key
        'SECRET': os.environ.get('NEXMO_API_SECRET'),     # Your Nexmo API Secret
        'FROM': 'MyApp',                                   # Sender ID (alphanumeric or phone number)
    },
    'TOKEN_LENGTH': 6,
    'MIN_TOKEN_LENGTH': 6,                                 # Minimum allowed token length for security
    'MAX_FAILED_ATTEMPTS': 5,                             # Maximum failed verification attempts before locking session
    'MESSAGE': 'Welcome to {app}! Please use security code {security_code} to proceed.',
    'APP_NAME': 'MyApp',
    'SECURITY_CODE_EXPIRATION_SECONDS': 600,
    'VERIFY_SECURITY_CODE_ONLY_ONCE': True,
}

Important

Security Best Practice: Never hardcode credentials in your settings file. Use environment variables or a secrets management system. See Security Best Practices for more details.

Step 5: Set Up Environment Variables#

Create a .env file in your project root (and add it to .gitignore):

# .env (for Twilio)
TWILIO_ACCOUNT_SID=your_account_sid_here
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+1234567890

Load environment variables in your settings.py:

# settings.py
from dotenv import load_dotenv
load_dotenv()  # Load .env file

Configuration Options Explained#

Here’s what each setting does:

  • BACKEND: The SMS backend class to use (Twilio, Nexmo, or custom)

  • OPTIONS: Provider-specific credentials and settings

    • Twilio: SID, SECRET, FROM

    • Nexmo: KEY, SECRET, FROM

  • TOKEN_LENGTH: Number of digits in the security code (recommended: 6)

  • MIN_TOKEN_LENGTH: Minimum allowed token length for security (default: 6). Prevents setting TOKEN_LENGTH to insecure low values

  • MAX_FAILED_ATTEMPTS: Maximum failed verification attempts before session lockout (default: 5). Protects against brute force attacks

  • MESSAGE: SMS message template. Variables: {app} and {security_code}

  • APP_NAME: Your application name (used in MESSAGE template)

  • SECURITY_CODE_EXPIRATION_SECONDS: How long codes are valid (in seconds). Recommended: 300-600 (5-10 minutes)

  • VERIFY_SECURITY_CODE_ONLY_ONCE: If True, codes can only be used once

For detailed configuration options, see the Configuration Reference reference.

Testing Your Setup#

You can quickly test if everything is working using the Django shell:

python manage.py shell

>>> from phone_verify.services import send_security_code_and_generate_session_token
>>> from phone_verify.services import verify_security_code
>>>
>>> # Send verification code
>>> phone = "+1234567890"  # Use your real phone number for testing
>>> session_token = send_security_code_and_generate_session_token(phone)
>>> print(f"Session token: {session_token}")
>>>
>>> # Check your phone for the SMS, then verify
>>> code = "123456"  # Enter the code you received
>>> verify_security_code(phone, code, session_token)
(<QuerySet []>, 'SECURITY_CODE_VALID')

If you see 'SECURITY_CODE_VALID', congratulations! Your setup is working correctly.

Tip

Testing Without Real SMS: To test without sending actual SMS messages, use a sandbox backend. See Customization Guide for how to create a sandbox backend that returns a fixed code.

Next Steps#

Now that you have django-phone-verify installed and configured, you can:

  1. Integrate into your app - See Integration Guide for examples of integrating phone verification into user registration, login, etc.

  2. Explore advanced use cases - Check out Advanced Examples for 2FA, password reset, and more

  3. Customize the backend - Write your own SMS backend in Customization Guide

  4. Secure your implementation - Review Security Best Practices for production best practices

  5. Troubleshoot issues - Visit Troubleshooting if you encounter any problems

Contents