Django OTP verification with the Fast2SMS OTP widget

This guide adds Django OTP verification to your project with the Fast2SMS OTP widget. The kit is a small reusable app, f2s_otp, with an endpoint view, limits stored in Django’s cache, a token helper and the widget’s static file. Visitors verify their mobile number by SMS or WhatsApp, and your view checks a signed token before it creates an account or logs someone in.

Download the Django OTP widget kit (zip)fast2sms-otp-widget-django.zip · 46 KBDownload .zip

We tested this kit with Django 6.1.3 (a throwaway project with the LocMem cache) against a mock copy of the Fast2SMS API, so no real SMS was sent: 47 of 47 browser and API checks passed. The app supports Django 4.2 and newer.

Before you start

  • A Fast2SMS account with wallet balance, and an approved DLT OTP template (SMS) or WhatsApp Authentication/Utility template.
  • A Django 4.2+ project. The app needs no extra Python packages.

Set up Django OTP verification

  1. Create a Smart OTP template and copy its OTP ID

    In the panel, open Smart OTP > OTP Template List and click Add OTP Template. On the SMS Channel tab, pick your DLT entity, sender and approved OTP template, then click the variable that should carry the code. For WhatsApp, use the WhatsApp Channel tab with an approved Authentication or Utility template. Tick SET FALLBACK TEMPLATE if you want the other channel as a backup, then click Assign OTP Template.

    Copy the 10-character OTP ID from the new card. It decides the channel, the template and the fallback for every code the widget sends.

    Smart OTP Template list with SMS and WhatsApp template cards, each showing its OTP ID with a copy icon
    Each template card shows its 10-character OTP ID with a copy icon.
  2. Copy your API key

    Under Utility in the left menu, click API Key. Click View (the panel first asks for an OTP sent to your registered mobile) and copy the Authorization Key. Check that API Access is switched on. This key will live only in your backend’s settings, never in a page or an app.

    API Key page with the masked Authorization Key, View and Reset buttons and the API Access switch turned on
    Copy the Authorization Key. API Access must be on.
  3. Add the app and its settings

    Copy the f2s_otp folder into your project and add it to INSTALLED_APPS. Set FAST2SMS_API_KEY, F2S_OTP_ID and F2S_TOKEN_SECRET (32 or more random characters) as environment variables, or the non-secret ones in an F2S_OTP dictionary:

    # settings.py
    INSTALLED_APPS = [
        # ...
        "f2s_otp",
    ]
    
    # Either set FAST2SMS_API_KEY, F2S_OTP_ID and F2S_TOKEN_SECRET as environment variables,
    # or put the non-secret ones here. Keep the API key itself in the environment.
    F2S_OTP = {
        "F2S_OTP_ID": "YOUR_OTP_ID",
        "F2S_RESEND_WAIT": 30,
    }

    Django will not start while a required setting is missing: ImproperlyConfigured lists the problems.

  4. Add the URLs

    # urls.py
    from django.urls import include, path
    
    urlpatterns = [
        # ...
        path("", include("f2s_otp.urls")),  # POST /f2s-otp, plus demo pages
    ]

    This adds POST /f2s-otp and two demo URLs. Open /f2s-otp-demo/ to try the widget. Remove the demo URLs in production: keep only the f2s-otp path from f2s_otp/urls.py.

  5. Add the widget to a template

    {% load static %}
    <script src="{% static 'f2s_otp/f2s-otp-widget.min.js' %}" defer></script>
    <div data-f2s-otp data-endpoint="/f2s-otp"></div>

    To make a form wait for OTP, add data-f2s-protect data-endpoint="/f2s-otp" to the <form>. The widget adds a hidden f2s_token field after verification. Keep Django’s own {% csrf_token %} in that form as usual.

  6. Check the token in your view

    from django.http import HttpResponseForbidden
    from f2s_otp.views import verify_token
    
    def signup(request):
        v = verify_token(request.POST.get("f2s_token"), mobile=request.POST.get("phone"))
        if v is None:
            return HttpResponseForbidden("Mobile number not verified.")
        # v["mobile"] is the verified 10-digit number. A token works only once.
        ...

    For OTP login, find the user by v["mobile"] and call Django’s login() here. Never trust the browser event alone.

Good to know

  • The endpoint is csrf_exempt on purpose. The widget sends no Django CSRF token. The view has its own protection instead: it checks the page’s Origin and requires an X-F2S-Widget header, which a browser cannot send cross-site without a CORS preflight. Your own forms keep Django’s CSRF check.
  • Limits use Django’s cache. The default LocMemCache is per process. With more than one process or server, configure a shared cache such as Redis, Memcached or the database cache, or the limits will not add up across workers.
  • Behind a proxy: set F2S_TRUST_PROXY=1 so the per-IP limit reads the real visitor IP. Only do this behind a proxy you control.
  • Same core as Flask: f2s_otp_core.py is shared with the Flask kit, and tokens use one format across the PHP, Python and Node kits.
OTP Settings page with Max Verify OTP Limit set to 5 and SMS Resend / Time Limit set to 30 seconds
Fast2SMS’s own limits. The widget’s limits run first, on your backend.

Settings

Setting Required Default What it does
FAST2SMS_API_KEY Yes Your API key, the bare key (no Bearer)
F2S_OTP_ID Yes The 10-character OTP ID from the template card
F2S_TOKEN_SECRET Yes 32 or more random characters; signs tickets and tokens
F2S_OTP_IDS No More OTP IDs a page may pick with data-otp-id, comma separated
F2S_ALLOWED_ORIGINS No same site only Other sites whose pages may call this backend
F2S_RESEND_WAIT No 30 Seconds between sends to one number
F2S_LIMIT_PER_NUMBER No 5 Sends per number per hour
F2S_LIMIT_PER_IP No 20 Sends per IP address per hour
F2S_MAX_VERIFY No 5 Wrong codes allowed per code
F2S_TOKEN_TTL No 600 Seconds a verified token stays valid
F2S_OTP_EXPIRY / F2S_OTP_LENGTH No 15 min / 6 digits Code expiry (1 to 10080 minutes) and length (4 to 10)
F2S_CAPTCHA / F2S_CAPTCHA_SECRET No off turnstile or recaptcha, plus its secret key

Sending, resending and cost

The view checks the origin, the header, the resend wait and the limits before it calls Fast2SMS Smart OTP. A new code for a number cancels the older one. “Code sent” means Fast2SMS accepted it; delivery shows in Smart OTP > Delivery Report.

Resend sends the same code again, it does not make a new one. Fast2SMS allows it within 10 minutes of the first send, and up to 5 sends to one number in that time, counting the first.

Every send and every resend is charged at your Smart OTP rate, and a fallback message on the second channel is charged too. Verify is free. The Test OTP button on a template card is also a real, charged send. See the current rates on the OTP SMS page.

Sending in bulk? For high OTP volumes our team offers discounted rates. Talk to our team or see OTP pricing.

Common problems and fixes

What you see Why Fix
Django will not start: ImproperlyConfigured A required setting is missing or wrong Set FAST2SMS_API_KEY, F2S_OTP_ID (10 characters) and F2S_TOKEN_SECRET (32 or more).
403 on /f2s-otp from your own page Usually the origin check: the page is on another domain or port Add the page’s origin to F2S_ALLOWED_ORIGINS.
“We could not send the code right now.” An account or setup problem. Your server log names it: failed reason=... invalid_otp_id: copy the OTP ID again, from the same account as the key. insufficient_balance: recharge with Add Amount. template_inactive: create a new OTP template. Auth error: check the key, switch on API Access, or whitelist the server IP in API Security.
“Please wait N seconds…” The resend wait: the widget’s own, or Fast2SMS’s Wait. Change F2S_RESEND_WAIT, or SMS Resend / Time Limit in OTP Settings.
“Too many requests” The per-number or per-IP limit was hit Wait an hour, or raise F2S_LIMIT_PER_NUMBER / F2S_LIMIT_PER_IP.
“Too many wrong tries” F2S_MAX_VERIFY, or Max Verify OTP Limit in OTP Settings The visitor asks for a new code.
Your form handler says “not verified” The token is missing, was used already, is older than 10 minutes, or is for another number Verify again. Check the token once, when the form is submitted.

Frequently asked questions

Which Django versions does the kit support?

Django 4.2 and newer. It was tested with Django 6.1.3.

Why is the endpoint exempt from CSRF?

The widget sends JSON with a custom X-F2S-Widget header and the view checks the page’s origin, which together block cross-site requests. Your own forms still use Django’s CSRF token.

Can I use Django REST Framework?

The kit uses a plain Django view, so it works next to DRF. If you want it inside a DRF view, call the same core from there; that setup is not included or tested.

I want a ready OTP login page in Django. Which kit?

Use the Django OTP login starter kit. The widget adds verification to pages you already have.

Where do I see if the OTP was delivered?

In Smart OTP > Delivery Report in the panel. The widget only knows that Fast2SMS accepted the send.

Is verify charged?

No. Each send and each resend is charged; verify is free.