Skip to Content

OTP & Zero-Knowledge MFA

Compare turnkey v1 OTP with v2 Zero-Knowledge SHA-256 Challenge-Response verification and automatic WhatsApp-to-SMS failover.

View Markdown (.md)

SMS Pro provides two verification tiers: v1 Turnkey OTP/MFA for rapid integration and v2 Zero-Knowledge Challenge-Response for security-sensitive fintech and enterprise applications.

Zero-Knowledge Nonce Proof Protocol (v2)

On v2 endpoints (POST /api/v2/public/otp/verify and POST /api/v2/public/mfa/verify), raw user-entered PIN codes are never transmitted over HTTP:

  1. Challenge Issuance: POST /api/v2/public/otp/send delivers the numeric PIN out-of-band to the user's phone and returns a 128-bit single-use challengeNonce (32 hex chars) to your backend/client.
  2. Canonical String Construction: Concatenate normalized nonce and user PIN:
    canonical = challengeNonce.trim().toLowerCase() + ":" + userCode.trim().toLowerCase()
  3. Cryptographic Proof: Compute lowercase hex SHA-256 over the canonical string:
    codeProof = hex(sha256(canonical))
  4. Verification: Submit challengeNonce (or otpId) and codeProof to /api/v2/public/otp/verify. The proof is checked once and cannot be reused.

Interactive Walkthrough Available

Follow the step-by-step code walkthrough in the Zero-Knowledge OTP Verification Recipe.

Multi-Factor Authentication (MFA) Policies

Create reusable verification policies via POST /api/v1/public/mfa/workflows to standardize:

  • codeLength: 4 to 8 digits
  • expiryMinutes: 1 to 60 minutes
  • maxAttempts: 1 to 10 verification attempts
  • resendCooldownSeconds: 10 to 300 seconds
  • channel: SMS, WHATSAPP, or AUTO_FAILOVER
  • defaultProofMode: CHALLENGE_RESPONSE or PLAIN

Automatic WhatsApp-to-SMS Failover

When a workflow or OTP challenge starts over WhatsApp and the subscriber fails to receive or confirm within the delivery window, call POST /api/v2/public/otp/failover (or POST /api/v1/public/otp/failover) to immediately fall back to carrier SMS (channelDelivered: "SMS_FAILOVER").

On this page