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)Download .zip
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
.envwith Node’s built-inprocess.loadEnvFile, so it needs no dotenv package.
Set up Node.js OTP verification
-
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.

Each template card shows its 10-character OTP ID with a copy icon. -
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.

Copy the Authorization Key. API Access must be on. -
Install and fill in .env
Unzip the kit, then:
npm install cp .env.example .envOpen
.envand 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-charactersNever commit
.env. The kit’s.gitignorealready lists it. -
Run the demo
Run
npm startand openhttp://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. -
Add the endpoint to your own app
Copy
f2s-otp-core.mjsinto your project. It has no dependencies. Then add the route fromserver.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.jsas 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> -
Check the token before you trust the number
The widget gives your page a token on
f2s:verified, or puts it in a hiddenf2s_tokenfield when the form hasdata-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.mobileand 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=1so the per-IP limit reads the visitor’s IP fromX-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 includesUpstashRedisStore, or write your own withincr,get,setanddel. - 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.