Two-Factor Authentication API

Two-factor authentication asks for a second, independent proof alongside the password: something you know plus something you have. The independence is the whole point. A leaked password database is worth much less when it does not, by itself, open any account.

The second factor only helps insofar as it is genuinely separate. A code emailed to an address protected by the same password is not a second factor; a proof tied to a physical device is.

SMS is the most widely deployed second factor and the weakest one still in common use. Codes can be redirected by a SIM swap, phished by a convincing page that simply asks the user to read them out, and delayed or lost by carrier routing. Each send also costs money, which makes the login path a place attackers can spend your budget.

None of this makes SMS 2FA worthless — it is enormously better than no second factor. It does mean that if you are choosing today, there is little reason to choose it as the default.

Sending the challenge over WhatsApp instead removes the carrier from the path: delivery is over the internet, the message is end-to-end encrypted, and there is no per-SMS charge. It also lands in an app the user already has open in most markets.

On its own, though, this fixes delivery and cost rather than the underlying weakness. A code is still a code, and a user who can read one can be talked into repeating it to an attacker.

Reverse OTP changes what the second factor is. Rather than sending a secret to the device and asking the user to relay it, it asks the device to send a message. The user taps a link and presses send; the server matches the incoming message to the pending login session.

That removes the phishable artefact entirely. There is no code on screen for a user to read out, nothing in transit to intercept, and nothing a SIM swap can redirect — the proof comes from a WhatsApp account bound to the handset, not from a number a carrier can reassign.

The API calls are the same two used at signup. When a login needs a second factor, open a session with POST /start-verification using an identifier tied to that login attempt, and present the returned deep link. Hold the session open server-side and complete the login only when GET /check-verification-status reports verified.

Two rules keep this sound. Bind the verification session to the login attempt, not to the user, so a completed session can never authorise a different one. And compare the number the API returns against the number stored on the account — a verified number that is not this user's number is a failed second factor, not a passed one.

Offer SMS as a fallback where WhatsApp is unavailable, on the same session, so a user in a low-adoption market is not locked out. Beyond that, plan for the case where the phone itself is gone: a second factor with no recovery path is an outage waiting to happen, and users who lose access tend to lose the account with it.

Recovery codes issued at enrolment are the usual answer. Whatever you choose, decide it before launch — recovery designed during an incident is always worse.

For consumer products, phone-based second factors have a decisive advantage: users already have the device and need to enrol nothing. That is why adoption for them is far higher than for authenticator apps or hardware keys.

For accounts protecting serious value — administrative access, financial control, infrastructure — a hardware security key remains the stronger choice, and the two combine well. Use phone verification where breadth matters and keys where depth does.