Recipe: Passwordless SMS sign-in

Goal

Let existing users sign in by receiving a one-time code at their registered phone number and typing it back. The user proves they control the phone; the platform verifies the code and issues a session. No password at any point.

When to use it

This pattern fits mobile-first products and markets where users navigate the world by phone number rather than email address. OTP-to-phone is the mental model many consumer apps have already trained users on — it's fast, familiar, and removes password management entirely from the user's responsibilities.

The tradeoff: sign-in security is bounded by possession of the phone and by the carrier's SIM-swap protections. For products with sensitive financial exposure or regulated data, pair this flow with a second factor rather than relying on SMS alone.

For a comparable flow using email instead of phone, see the Passwordless login via OTP email recipe.

What you will build

The platform ships a default SMS-login flow automatically on every tenant. Enabling SMS OTP in Authentication → SMS OTP is enough to activate it for your users. The flow the platform uses looks like this:

SMS login flow
  Step: Telemetry capture        (records request metadata for the risk engine)
  Step: Identity lookup          (resolves the phone number to the user)
  Step: Send + verify code       (dispatches the six-digit OTP by text, then pauses
                                  for the user to type the code back)
  Step: Issue session            (mints the session and signs the user in)

The "send and verify" step is a single atomic block. The platform sends the code and waits for the user to submit it in the same step — there is no separate send and verify pair. This keeps the OTP lifecycle atomic: the code is valid only until the user submits it or it expires.

Configure it

Step 1 — Add a phone trait to your identity schema

The SMS login flow resolves the phone number the user types against the phone trait stored on their identity. If your schema has no phone trait, the lookup fails for every user.

Go to Users → Identity schema and confirm there is a phone-type field. If not, add one. Mark it as an identifier so users can sign in with it.

If you are already collecting phone numbers during registration (for SMS MFA, for example), the trait is already there — skip to step 2.

Step 2 — Configure the SMS gateway

The platform sends codes through BulkPush. If you have not already configured the gateway, do so now. Your cluster operator supplies the gateway URL, username, feed ID, and password at deploy time. Once the gateway is wired, the platform will dispatch real codes rather than logging them silently. Confirm the gateway is live by requesting a test code from the sign-in page.

If you are deploying in India, register your SMS template on the DLT portal before enabling — carriers drop unregistered templates silently. See SMS OTP — DLT template registration.

Step 3 — Enable SMS OTP

Go to Authentication → SMS OTP and toggle it on. Save.

This step publishes the SMS login flow if it is not already published, and adds the "Text message" tab to the sign-in page.

That is the complete setup. The platform handles the rest.

Test it

Navigate to your tenant's sign-in page — https://<tenant>-<org>.intelliauth.local/login or your production equivalent.

Select the "Text message" tab.
Enter the phone number of a test user (a user whose profile has a matching phone trait).
Click "Send verification code."
Check the phone for the code. If the gateway is in stub mode (credentials not configured), no text is dispatched and the code is held on the server side only — ask your cluster operator to check the platform logs, or finish configuring the gateway and try again.
Enter the code in the sign-in form.
Confirm you are redirected to the dashboard (or the post-auth redirect you configured).

To test the failure paths:

Enter a phone number with no matching user — confirm the page shows the same "sent" confirmation as a valid number (anti-enumeration).
Enter the wrong code several times — confirm the lockout message appears once the failed-attempt threshold is hit.
Wait for the code to expire (about 15 minutes) without entering it — confirm the expired-code error appears with a prompt to request a new code.

Cautions

Anti-enumeration is essential. The sign-in form must show the same "We sent a code" message whether or not the phone number is registered. Showing "no account found for this number" tells an attacker exactly which numbers are in your user base. The platform enforces this by design — your custom UI should do the same if you have one.

SMS delivery is not guaranteed. A user in a poor signal area, roaming internationally, or on a carrier with aggressive filters may not receive the code. Provide a clear "Didn't get a code? Resend" affordance with a visible cooldown. For products where missed SMS is a critical support driver, consider offering email OTP as an alternative tab.

The gateway fails open. If the SMS gateway is unreachable at the moment a code is dispatched, the step logs a warning and the user never receives the code. The session is not issued (the user cannot supply a code they never received), but the sign-in form shows the usual "we sent a code" confirmation. Monitor gateway errors in the audit log during rollout.

DLT registration for India is mandatory. Codes sent to Indian numbers without a registered template are dropped by the carrier with no error returned to the platform. Verify registration before enabling for Indian user bases.