# Fast2SMS OTP widget kits

> Drop-in OTP verification (SMS + WhatsApp with fallback, via Fast2SMS Smart OTP) for any website or app. A dependency-free JS widget talks to the customer's own small backend endpoint; the backend holds the Fast2SMS API key and calls /dev/otp/send, /dev/otp/verify and /dev/otp/resend. After verification the backend issues a signed, short-lived, one-time token that the customer's server checks. MIT licensed.

Key facts:
- Embed: `<script src="f2s-otp-widget.min.js" defer></script>` + `<div data-f2s-otp data-endpoint="/f2s-otp"></div>`. Protect a form: `<form data-f2s-protect data-endpoint="/f2s-otp">` adds hidden `f2s_token`.
- Contract: POST <endpoint>, headers `Content-Type: application/json` and `X-F2S-Widget: 1`, body `{"action":"send"|"verify"|"resend","mobile":"9876543210","otp"?,"ticket"?,"otp_id"?,"captcha"?}`. Answers `{"ok":true,...}` or `{"ok":false,"reason":"...","message":"..."}`.
- Required backend env: FAST2SMS_API_KEY (bare key, sent as `authorization` header), F2S_OTP_ID (10-hex OTP ID from Smart OTP -> OTP Template List), F2S_TOKEN_SECRET (32+ chars). Optional: F2S_OTP_IDS allowlist, F2S_ALLOWED_ORIGINS, limits, captcha (turnstile/recaptcha).
- Never expose the API key to browsers or apps. Never use route=otp (discontinued). Never forward a client otp_id that is not in the allowlist. Never retry a send that may have reached Fast2SMS.
- Token format: `v1.<base64url(json)>.<base64url(HMAC-SHA256)>`, same in PHP, Python, Node and Apps Script. Check it with the kit helper (verifyToken / verify_token / f2sow_verify_token).
- Indian mobile numbers only (10 digits, 6-9). Each send and resend is charged; verify is free.

## Docs
- [README.md](README.md): choose your setup, 5-minute setup, security summary
- [CONTRACT.md](CONTRACT.md): JSON contract, reason codes, token format, all settings, security rules
- [AGENTS.md](AGENTS.md): rules and file map for AI coding assistants
- [widget/README.md](widget/README.md): attributes, JS API, events, theming, site builders
- [TEST-REPORT.md](TEST-REPORT.md): what was tested and what was not run

## Backends (same contract)
- [backends/php-single-file](backends/php-single-file/README.md): one PHP file, any hosting
- [backends/node-express](backends/node-express/README.md): Node.js 20+ / Express 5
- [backends/python-flask](backends/python-flask/README.md): Flask 3
- [backends/django](backends/django/README.md): Django app (uses Django cache for limits)
- [backends/laravel](backends/laravel/README.md): controller + route + config snippet
- [backends/cloudflare-worker](backends/cloudflare-worker/README.md): Worker (+ optional KV)
- [backends/vercel-netlify-function](backends/vercel-netlify-function/README.md): Vercel and Netlify functions (+ optional Upstash)
- [backends/google-apps-script](backends/google-apps-script/README.md): Google-hosted OTP-verified form that saves to a Google Sheet

## Examples (call the customer backend, never Fast2SMS)
- [examples/plain-html](examples/plain-html/README.md), [react](examples/react/README.md), [nextjs](examples/nextjs/README.md), [vue](examples/vue/README.md)
- [examples/wordpress](examples/wordpress/README.md): plugin "OTP Widget for Fast2SMS", shortcode [f2s_otp]
- [examples/shopify](examples/shopify/README.md): theme section + protect snippet
- [examples/flutter](examples/flutter/README.md), [android-kotlin](examples/android-kotlin/README.md), [ios-swift](examples/ios-swift/README.md), [react-native](examples/react-native/README.md)

## Optional
- Fast2SMS API docs: https://docs.fast2sms.com
- Smart OTP setup guide: https://www.fast2sms.com/help/smart-otp-setup-guide-fast2sms/
