The user types their phone number; the platform sends a six-digit code by text; they type the code; they're in. No password to remember or reset.
Prerequisites
Section titled “Prerequisites”Two things must be in place before you enable this:
A phone trait in your identity schema. The sign-in flow looks up the user by their phone number and dispatches the code to that number. If your schema has no phone-type trait, the flow has nowhere to look and will refuse sign-in attempts. Add the trait under Users → Identity schema before enabling SMS OTP.
A configured SMS gateway. The platform dispatches codes through BulkPush (or a BulkPush-compatible gateway). Wire this up first — see SMS gateway configuration below.
Enable
Section titled “Enable”Authentication → SMS OTP. Toggle on. Save.
Once on, a "Text message" tab appears on the sign-in page alongside whatever other methods you have enabled. The user selects it, enters their phone number in E.164 format (+<country-code><number>), and requests a code.
What the user sees
Section titled “What the user sees”- Sign-in page → "Text message" tab.
- Enter phone number (e.g.
+14155550100). - Click "Send verification code."
- A six-digit code arrives by text within a few seconds.
- Type the code into the verification form.
- Signed in.
The code expires after 15 minutes. If it never arrives, the user can click "Resend code" once the cooldown period passes.
SMS gateway configuration
Section titled “SMS gateway configuration”The platform sends codes via BulkPush. Your cluster operator configures the gateway at deploy time using Helm chart values. The values needed are:
| Value | Description | Example |
|---|---|---|
sms.gatewayUrl | Full URL of the BulkPush API endpoint | http://bulkpush.mytoday.com/BulkSms/SingleMsgApi |
sms.username | BulkPush feed username | Your 10-digit MSISDN |
sms.feedId | BulkPush numeric feed ID | Assigned by BulkPush |
sms.password | BulkPush feed password | Supplied as a sealed secret — not in chart values |
When any of these is missing, the platform logs a warning and falls back to stub mode: it writes the OTP to its own log instead of dispatching by text. Users will not receive codes. Verify your gateway is wired by sending a test message after configuration.
DLT template registration (India)
Section titled “DLT template registration (India)”If you route messages to Indian phone numbers, the Telecom Regulatory Authority of India (TRAI) requires all transactional SMS to use a pre-registered DLT template. A request dispatched without a registered template is dropped by the carrier with no delivery confirmation or error.
Register your template on the DLT portal your carrier provides. The platform's default SMS body is:
Dear User, {otp} is the One Time Password (OTP) to access {app_name}. OTPs are SECRET. DO NOT disclose it to anyone.Where {otp} is replaced by the six-digit code at dispatch time. Match this template exactly when registering on the DLT portal, or register a custom template and update it in the SMS settings.
SMS message body
Section titled “SMS message body”The SMS message body is set at the operator layer alongside the gateway credentials and applies cluster-wide. If you need different SMS copy, coordinate with your cluster operator. The replacement marker for the code is {otp}. Keep the message short — carriers may truncate long messages, and the code must be clearly visible.
When to enable SMS OTP
Section titled “When to enable SMS OTP”SMS sign-in suits products where:
- Users are on mobile and a phone number is the natural identifier (rather than email).
- Your user base lacks reliable access to email (some markets, some demographics).
- You want passwordless sign-in and email OTP is already in use for a different sign-in audience.
When NOT to use SMS OTP as the primary method:
- High-security tenants. SIM swap is a real attack. An attacker who convinces a carrier to redirect a user's number can intercept every sign-in code. If your product involves financial data, sensitive healthcare records, or admin access, keep password + TOTP or WebAuthn as the primary and offer SMS only as a fallback.
- B2B internal tools. Enterprise users have company email and SSO. SMS adds nothing here.
Rate limits
Section titled “Rate limits”The platform protects the SMS channel from abuse with three independent limits:
- Per-user send rate — a single user cannot request unlimited codes; once they hit the per-hour cap they are asked to wait before requesting another.
- Per-IP send rate — defends against attackers walking phone numbers from a single source by capping sends across all users from one origin.
- Failed-code lockout — entering the wrong code repeatedly burns the current code and triggers a brief lockout, after which the user can request a fresh code.
When a rate limit is hit, the sign-in page shows a message asking the user to wait before retrying. Exact thresholds are tuned at the operator layer.
Security considerations
Section titled “Security considerations”Anti-enumeration. When a phone number has no matching user, the platform returns the same "We sent a code" confirmation as for a valid number. The code is never delivered, but the user gets no signal that the number is unregistered. This prevents enumeration of your user base by phone number.
SIM swap. SMS codes are interceptable if an attacker succeeds in a SIM swap against a user's carrier. For most consumer products the risk is acceptable. For high-value accounts, treat SMS as a fallback only and encourage users to enrol TOTP or WebAuthn as their primary MFA factor.
Common questions
Section titled “Common questions”"Can users sign up via SMS OTP?"
No — SMS OTP is a sign-in method for existing accounts. A user must already have a record with a registered phone number. Registration goes through the standard password + identity schema form; the phone number is collected as a trait during sign-up.
"What if a user changes their phone number?"
They sign in with the old number, go to their account settings, and update the phone trait. Once updated, they use the new number on the next sign-in. Admins can also update the phone trait directly via the user detail page.
"Does SMS OTP also work for MFA?"
Yes. When SMS is enabled as a primary sign-in method, users who have a phone trait can also enrol their phone number as an MFA factor (a second factor on top of a password sign-in). The enrollment happens at the same phone number stored on their identity. See MFA overview.