Node.js Express OTP verification with the Fast2SMS OTP widget

This guide adds Node.js OTP verification to an Express app with the Fast2SMS OTP widget. You get a ready POST /f2s-otp endpoint that holds your API key and calls Fast2SMS Smart OTP, plus a browser box with code inputs and a resend timer. Visitors verify their mobile number by SMS or WhatsApp, and your server gets a signed token it can trust.

Download the Node.js Express OTP widget kit (zip)fast2sms-otp-widget-node-express.zip · 57 KBDownload .zip

We tested this kit with Node.js 24.18.0 and Express 5 against a mock copy of the Fast2SMS API, so no real SMS was sent: 47 of 47 browser and API checks and 6 of 6 unit tests passed.

Before you start

  • A Fast2SMS account with wallet balance, and an approved DLT OTP template (for SMS) or WhatsApp Authentication/Utility template (for WhatsApp).
  • Node.js 20.12 or newer. The kit reads .env with Node’s built-in process.loadEnvFile, so it needs no dotenv package.

Set up Node.js 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. Install and fill in .env

    Unzip the kit, then:

    npm install
    cp .env.example .env

    Open .env and set the three required values. The file’s comment shows a one-line command that makes a random secret.

    FAST2SMS_API_KEY=YOUR_API_KEY
    F2S_OTP_ID=YOUR_OTP_ID
    F2S_TOKEN_SECRET=at-least-32-random-characters

    Never commit .env. The kit’s .gitignore already lists it.

  4. Run the demo

    Run npm start and open http://127.0.0.1:3000. The demo page has a login box and a sign-up form that needs a verified number. If a required setting is missing, the server does not start and prints which one.

  5. Add the endpoint to your own app

    Copy f2s-otp-core.mjs into your project. It has no dependencies. Then add the route from server.mjs:

    import express from 'express';
    import { loadConfig, createOtpEndpoint } from './f2s-otp-core.mjs';
    
    const otp = createOtpEndpoint(loadConfig(process.env)); // throws if a required setting is missing
    const app = express();
    
    app.all('/f2s-otp', express.json({ limit: '8kb' }), async (req, res) => {
      const r = await otp.handle({
        method: req.method,
        headers: req.headers,
        body: req.is('application/json') ? req.body : null,
        ip: String(req.ip || '').replace(/^::ffff:/, ''),
        host: req.headers.host,
      });
      res.status(r.status).set(r.headers);
      if (r.body === null) res.end();
      else res.send(JSON.stringify(r.body));
    });

    Serve f2s-otp-widget.min.js as a static file and add the widget to your page:

    <script src="/f2s-otp-widget.min.js" defer></script>
    <div data-f2s-otp data-endpoint="/f2s-otp"></div>
  6. Check the token before you trust the number

    The widget gives your page a token on f2s:verified, or puts it in a hidden f2s_token field when the form has data-f2s-protect. Check it on the server:

    app.post('/signup', express.urlencoded({ extended: false }), async (req, res) => {
      const v = await otp.verifyToken(req.body.f2s_token, { mobile: req.body.phone });
      if (v === null) return res.status(403).send('Mobile number not verified.');
      // v.mobile is the verified 10-digit number. A token works only once.
      // create the account or start the session here
    });

    For OTP login, find the user by v.mobile and start the session here. Never log a user in from the browser event alone.

Going live

  • The demo server listens on 127.0.0.1 only. Put it behind nginx or your load balancer, and set F2S_TRUST_PROXY=1 so the per-IP limit reads the visitor’s IP from X-Forwarded-For. Set it only behind a proxy you control.
  • Limits live in memory, so they work for one process. With PM2 cluster mode or several servers, pass a shared store: createOtpEndpoint(config, { store }). The core includes UpstashRedisStore, or write your own with incr, get, set and del.
  • API Security: if it is on in your account, whitelist your server’s outgoing IP. See IP whitelisting.
  • React or Vue front end: the kit’s examples wrap the same widget. The React example was tested (3 of 3 checks); the Vue example has not been run yet.

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 backend checks the page’s origin, the X-F2S-Widget header, the resend wait and the limits before it calls Fast2SMS. It never retries a send that may have reached Fast2SMS, so a timeout cannot charge you twice.

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
The server exits at start and lists settings A required setting is missing or wrong Set FAST2SMS_API_KEY, F2S_OTP_ID (10 characters) and F2S_TOKEN_SECRET (32 or more).
“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.
“This page is not allowed to use this OTP service.” The page is on another domain Add its origin (https:// plus the domain, no path) to F2S_ALLOWED_ORIGINS.
“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 Node.js version does the kit need?

Node.js 20.12 or newer, with Express 5. It was tested on Node.js 24.18.0.

Can I use the core without Express?

Yes. f2s-otp-core.mjs has no dependencies and is the same code the Cloudflare Worker, Vercel and Netlify kits use. Pass it the method, headers, body, IP and host of each request.

Should I call Fast2SMS from my React app directly?

No. That would put your API key in the browser. The React app talks to your Express endpoint, and only Express talks to Fast2SMS.

I want a complete OTP login page. Which kit?

Use the Node.js Express OTP login starter kit. The widget is for adding verification to pages you already have.

How do I limit costs from bots?

Keep the per-number and per-IP limits on, use a shared store when you run more than one process, and switch on the optional Turnstile or reCAPTCHA check with F2S_CAPTCHA.

Is the token a JWT?

No. It is a short signed string in its own format, made with HMAC-SHA256. Check it only with verifyToken, which also makes sure it is used once.