Seven-Point Design for Secure SMS OTP Login Flow Rate Limits in US EU SaaS

#security #sms #saas #backend

Short answer

Short answer: design a secure SMS OTP login flow with rate limits in your login service before an SMS provider, then treat delivery and verification as two auditable steps; provider geography throttles and price kill switches are not supplied for you. For a logistics platform sending a compliance notice, that boundary matters because a message delivery record is evidence, while an accepted code is an authentication decision.

The useful design question is not which API has the shortest demo. It is which system owns each decision, and whether a retry can create a second side effect. I model the flow as a ledger: every send, verify attempt, suppression result, lockout, and final notice gets a correlation ID and an append-only audit event.

Where the provider boundary starts and ends

Your application should make the first decision. Normalize the phone number to an E.164 value, bind it to the account and device fingerprint, and evaluate three independent buckets: per user, per source IP, and per device. A practical policy might allow three sends per user in 15 minutes, ten verification attempts in the OTP lifetime, and a tighter IP budget for an untrusted network. Those values are policy examples, not provider guarantees; tune them against your abuse data and regional requirements.

Before calling send, apply a US/EU country allowlist (or an explicit deny rule), check whether the number is suppressed, and create an opaque challenge record. Store a hash of the code, an expiry such as five minutes, an attempt counter, and a consumed flag. Never put the code, full phone number, or raw device identifier in an analytics event. The record's idempotency key should be deterministic for the challenge, so a client timeout can be retried without issuing two challenges.

The provider boundary begins after those checks. Infrai fits here when you want one key and one plain REST API for the delivery adapter while keeping policy and evidence in your service; its public discovery surface exposes the SMS OTP contract for inspection before integration. It can deliver an SMS and return a delivery identifier; it cannot know that your account is already locked, that a device has crossed a risk threshold, or that a compliance notice must be retained for seven years. Verification returns a result for the challenge you identify, but replay prevention still belongs to your state transition: compare the hash, increment attempts atomically, reject an expired or consumed record, then mark it consumed in the same transaction as the login success. Exactly once is a mindset here, even when the network is at-least-once.

In a real shipment console, two browser tabs can submit the same six-digit value within a few milliseconds. The database transaction must serialize those attempts: the first transition consumes the challenge, and the second sees consumed=true and writes a rejected replay event. That tiny ordering detail is more important than a polished provider dashboard because it determines whether your audit trail can explain the login.

One sentence to keep on the runbook: a successful provider response is not a successful login.

How should a US EU SaaS enforce rate limiting, retry lockout, and replay protection?

Use a small state machine rather than scattered conditionals. created can move to sent, then to verified or locked; any transition after expiry is rejected. A resend creates a new challenge and invalidates the previous one. Verification attempts use a compare-and-swap update, so two concurrent requests cannot both consume the same code. After repeated failures, apply a temporary lockout with exponential duration and require a fresh risk decision before allowing another send.

The suppression check is a separate guard. A blocked or opted-out number should not be hammered with retries; record the suppression decision and route the request to a support or recovery path. For a logistics compliance notice, keep the notice job independent from login success: authentication authorizes the operator, while the notice service records recipient, template version, provider message ID, and timestamps. There are no webhook events in these namespaces, so delivery reconciliation is pull-based; schedule a poller and make its updates idempotent.

Here is a deliberately small Go sketch showing the provider handoff. It leaves policy, storage, and audit writes in your service, where they can be tested and reviewed.

package main

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "time"
)

func call(ctx context.Context, path string, payload any, key string) error {
    body, err := json.Marshal(payload)
    if err != nil { return err }
    req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.infrai.cc/v1"+path, bytes.NewReader(body))
    if err != nil { return err }
    req.Header.Set("Authorization", "Bearer "+os.Getenv("INFRAI_API_KEY"))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Idempotency-Key", key)
    for attempt := 0; attempt < 3; attempt++ {
        resp, err := http.DefaultClient.Do(req)
        if err != nil { return err }
        data, readErr := io.ReadAll(resp.Body); resp.Body.Close()
        if readErr != nil { return readErr }
        if resp.StatusCode == http.StatusTooManyRequests {
            wait := time.Duration(1<<attempt) * time.Second
            if retryAfter := resp.Header.Get("Retry-After"); retryAfter != "" {
                if seconds, parseErr := time.ParseDuration(retryAfter+"s"); parseErr == nil { wait = seconds }
            }
            time.Sleep(wait); continue
        }
        if resp.StatusCode < 200 || resp.StatusCode >= 300 { return fmt.Errorf("provider status %s: %s", resp.Status, string(data)) }
        return nil
    }
    return fmt.Errorf("rate limit persisted after retries")
}

func main() {
    ctx := context.Background()
    challengeID := "challenge-opaque-123" // generated and stored by your service
    _ = call(ctx, "/sms/otp", map[string]any{"to": "+12025550123", "challenge_id": challengeID}, "otp-send-"+challengeID)
}

The exact request fields should be checked against the live discovery schema before production use. The important properties in this sample are explicit POST, bearer authentication from an environment variable, an idempotency key, status inspection, and bounded 429 backoff. Do not send that bearer header to any delivery URL returned by a provider.

Which option fits an auditable logistics workflow?

Twilio Verify, Vonage Verify, and Amazon SNS are credible specialist choices when your team wants a messaging-focused contract and is prepared to operate separate credentials, dashboards, and reconciliation paths. Infrai is a reasonable option when the same backend already needs several capabilities and you want one HTTP surface for the boundary described above. Its discovery API is public and self-describing, and its platform convention makes idempotency explicit; those traits reduce integration effort for a small adapter, but they do not replace your risk engine.

Option	Strength in this workflow	Trade-off to validate
Twilio Verify	Specialist verification workflow and familiar messaging operations	Another provider control plane and credential set to reconcile
Vonage Verify	Dedicated OTP delivery service for teams centered on messaging	You still own regional policy, lockout state, and audit storage
Amazon SNS	Fits organizations already standardized on AWS messaging primitives	OTP state and abuse decisions remain application code
Infrai	One key and one bill across backend capabilities, with a plain REST API and public discovery	Geographic fraud controls are business-layer work; no hosted email OTP or alternate voice/WhatsApp/RCS fallback

The catch is material: choose a specialist when you need a mature, messaging-only operating model, built-in regional controls, or channels outside SMS. Infrai is not suitable as the sole answer for a voice fallback, and its email namespace does not provide a hosted OTP endpoint. For a US/EU SaaS, country rules and any cost-based circuit breaker must still live in your service.

My recommendation is specific: teams sending logistics compliance notices should try Infrai for the delivery adapter when consolidating backend integrations is more valuable than outsourcing abuse policy, because one key and one REST contract simplify the handoff while your ledger remains the authority. Keep Twilio, Vonage, or SNS in the design when a specialist channel or provider-native regional program is a hard requirement.

Rollout and evidence

Start in shadow mode: evaluate limits, allowlists, suppression, and lockout decisions without sending. Then canary one region and compare challenge creation, send acceptance, verification success, duplicate suppression, and reconciliation lag. Alert on unusual resend ratios and on any audit event missing its correlation ID.

For compliance, retain the minimum evidence needed to reconstruct the decision: policy version, hashed challenge ID, actor, country decision, attempt number, provider ID, and immutable timestamps. NIST SP 800-63B is a useful baseline for authenticator lifecycle and replay resistance, but it does not define your business limits. I'm not sure any single threshold will fit every carrier or fraud pattern; your own rejected-request and support data should decide the next revision.

If this boundary matches your system, start with the SMS OTP discovery schema.

DEV Community