Send an OTP by SMS, with voice fallback

MFASMS OTP with voice fallback

The MFA API sends a code by SMS, re-sends it by voice call if asked, and verifies it; you store no codes.

Also called 2FA, two-factor authentication, one-time passcode, phone number verification

mfaidentity

The claim

One-time codes are a platform service, not something you generate, store, expire and rate-limit yourself. POST /mfa/sms creates and delivers a code, returning a request id. If SMS does not arrive, or the user is on a landline, POST /mfa/call reads the code out on a phone call instead. POST /mfa/{id}/verify checks what the user typed. Your application holds only the request id.

How it works

client.mfa.sms(to=to, **{"from": FROM}, message="Your verification code is: ",
               token_length=6, valid_for=300, max_attempts=3, allow_alphas=False)   # -> {"id": ...}
client.mfa.call(...)                                                                   # same parameters, by voice
client.mfa.verify(request_id, token=token)                                             # -> {"success": true|false}

Expiry (valid_for, seconds) and the attempt cap (max_attempts) are enforced by the platform. The Flask routes are the thinnest possible wrapper so the three calls are visible; in a real app the request id lives in the session.

This is a different thing from require-verification-before-unlocking-tools: that recipe gates an AI agent’s tools on a check; this one is the check.

What to change first

Use the verified request id to unlock an agent’s tools (require-verification-before-unlocking-tools) or to trust a caller ID in buy-a-number-and-point-it-at-your-app’s tenant onboarding.

Where this sits

Send an SMS

Require verification before unlocking AI agent tools

python/app.py

"""Send an OTP by SMS, with voice fallback.

The MFA API generates the code, delivers it by SMS or by a voice call, and
verifies what the user types back. Your application stores only the request
id; it never sees or stores the code.

Written against signalwire-sdk 3.0.1 (RestClient.mfa) and Flask.

  POST /otp/start   {"to": "+1555..."}                 -> {"request_id": ...}
  POST /otp/voice   {"to": "+1555..."}                 -> {"request_id": ...}  (fallback)
  POST /otp/verify  {"request_id": ..., "token": "..."} -> {"verified": true|false}
"""
import os

from dotenv import load_dotenv
from flask import Flask, jsonify, request
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

app = Flask(__name__)
client = RestClient()

FROM = os.getenv("SIGNALWIRE_PHONE_NUMBER", "+15550001111")
OPTIONS = {
    "message": "Your verification code is: ",
    "token_length": 6,
    "valid_for": 300,      # seconds
    "max_attempts": 3,
    "allow_alphas": False,
}


def send_by_sms(to):
    res = client.mfa.sms(**{"to": to, "from": FROM, **OPTIONS})
    return res["id"]


def send_by_voice(to):
    """Same code parameters, read out over a phone call."""
    res = client.mfa.call(**{"to": to, "from": FROM, **OPTIONS})
    return res["id"]


def check(request_id, token):
    res = client.mfa.verify(request_id, token=token)
    return bool(res.get("success"))


@app.post("/otp/start")
def start():
    return jsonify(request_id=send_by_sms(request.json["to"]))


@app.post("/otp/voice")
def voice():
    return jsonify(request_id=send_by_voice(request.json["to"]))


@app.post("/otp/verify")
def verify():
    body = request.json
    return jsonify(verified=check(body["request_id"], body["token"]))


if __name__ == "__main__":
    app.run(port=int(os.getenv("PORT", "8080")))

Run it

cd python
pip install -r requirements.txt
export SIGNALWIRE_SPACE=... SIGNALWIRE_PROJECT_ID=... SIGNALWIRE_API_TOKEN=... SIGNALWIRE_PHONE_NUMBER=+1555...
python app.py
curl -X POST localhost:8080/otp/start  -H 'content-type: application/json' -d '{"to": "+1555..."}'
curl -X POST localhost:8080/otp/verify -H 'content-type: application/json' -d '{"request_id": "...", "token": "123456"}'

Verify it

python verify.py          # from the recipe folder, not python/

With the HTTP layer recorded, the verifier checks the three documented MFA requests and their required bodies against tools/openapi/rest.json. It also confirms that the voice fallback carries the same parameters as the SMS send, and that the application generates no codes of its own.

Report an issue

Send an OTP by SMS, with voice fallback

The claim

How it works

What to change first

Where this sits

Related

Next