OTP flows on programmable SMS routing: a FastAPI implementation

#fastapi #python #backend #api

Most OTP examples stop too early.

They show how to generate a code, store it somewhere, and send an SMS through a provider that hides routing behind a black box.

That works for demos.

It breaks down when routing, pricing and delivery behavior matter.

At BridgeXAPI, messaging is approached differently.

Routing is not hidden.

It is part of the application.

To demonstrate that, we built a FastAPI OTP service on top of programmable SMS routing.

This is not just an OTP example

This is an example of what authentication flows look like when routing, pricing and delivery are part of your system — not abstracted away by a provider.

The routing model

Most messaging APIs follow this pattern:

you define the message
the provider selects the route
pricing and delivery behavior are opaque

In this model, routing is a black box.

BridgeXAPI follows a different approach:

the developer selects the route (route_id)
pricing is tied to that route
delivery behavior becomes predictable
routing decisions live in application code

This matters for OTP systems.

A login code is not the same as bulk messaging.

The delivery path should be explicit.

The FastAPI service

The service exposes two endpoints:

POST /send-otp
POST /verify-otp

Example request:

{
  "phone_number": "31651860670",
  "purpose": "login",
  "route_id": 3
}

Example response:

{
  "status": "otp_sent",
  "phone_number": "*******0670",
  "purpose": "login",
  "route_id": 3,
  "expires_in_seconds": 300,
  "cooldown_seconds": 45,
  "debug_code": "816369",
  "bx_message_id": "BX-22229-1d5e5779b1904695",
  "order_id": "22229",
  "delivery_status_url": "https://hi.bridgexapi.io/api/v1/dlr/BX-22229-1d5e5779b1904695"
}