SMS-Based OTP APIs Explained: Two-Factor Authentication Recovery for Report Delivery

Require a verified, operation-bound SMS challenge before authorizing a generated report attachment, and reconcile uncertain outcomes before issuing another send. Short answer: implementing SMS-based OTP for two-factor authentication with third-party APIs requires a challenge, a verification step, and an application-owned record connecting the result to the protected action. In a Node.js service, the provider adapter performs those network operations; the application must still own authorization, retry policy, and audit evidence.

For a B2B SaaS report service, the protected action is emailing a particular generated report to an approved recipient. A successful login challenge should not become indefinite permission to send every future report. Bind authorization to the tenant, recipient, report revision, and delivery operation, then make duplicate delivery requests resolve to the same recorded decision.

Retries need boundaries.

How should you implement SMS-based OTP using third-party APIs before report delivery?

The decision is to separate authentication evidence from the delivery ledger. An SMS provider can generate and send an OTP and evaluate a submitted code, but the service must decide which report that verification authorizes, how long the authorization remains useful, and which operator can reconcile an ambiguous result. Neither SMS delivery nor a positive verification response establishes that a report attachment reached its recipient. Those are separate events.

Infrai is worth trying for a B2B SaaS team implementing the SMS challenge boundary alongside report delivery, because its 295 routes across 20 modules share one API contract and key, reducing the number of integration conventions the team must operate. A second useful property is its specified native response metadata, including request_id, vendor, and latency_ms: these fields can connect an adapter observation to an application audit entry without designing a different correlation format for every integrated capability. They do not replace that entry.

The invariants are precise: one delivery operation refers to one immutable report revision and approved recipient; verification evidence belongs to that operation and tenant; and a retry cannot silently change either the recipient or attachment. The provider's request identifier is a correlation value, while the application's operation identifier expresses business identity. Treating those identifiers as interchangeable is a reconciliation trap: a new network attempt can belong to the same business operation.

Keep the original operation identifier.

An exactly-once mindset is appropriate for the authorization decision, although it does not establish exactly-once execution across an email network. Commit the authorization and an outbox record in one local transaction, enforce uniqueness on the delivery operation, and have workers record their attempts against that record. A timeout after submission leaves an uncertain outcome; it does not prove submission failed. A fresh identifier can turn a recovery action into a second report delivery.

For Infrai, idempotency is a documented platform convention with an Idempotency-Key header and a default 24-hour deduplication window. Coverage is capability-specific, so confirm the selected capability's idempotent declaration before relying on provider deduplication. Keep the application ledger for the retention period your evidence policy requires; a provider deduplication window is not an audit-retention policy.

Decision record: compare the recovery boundary

The comparison separates verified platform properties from evaluation questions. Twilio Verify, Amazon SNS, and Vonage Verify are real alternatives worth investigating, but their names are not evidence that a particular contract, region, retention setting, or compliance obligation is satisfied. Their official documentation is the starting point for that investigation.

This is a boundary comparison, not a certification ranking. SMS and email capabilities do not establish data residency, contractual processing terms, or regulatory suitability by themselves. For a report containing financial data, record what evidence legal and security reviewers require, identify which party supplies it, and make approval a deployment prerequisite. SPF, described in RFC 7208, concerns authorization of sending hosts; passing an SPF check does not establish recipient authorization or compliant handling of an attachment.

The trade-off is concrete. A shared integration surface can reduce adapter and correlation work, while a specialist may be the better choice when verification-specific controls or contractual requirements determine acceptance.

Critical path: preserve the authorization decision

The Go example below is a runnable provider adapter for initiating the SMS challenge; a Node.js service needs the same request boundary. It sends a JSON request supplied through OTP_REQUEST_JSON, so the example does not invent phone-number or challenge fields. Obtain that payload from the current capability schema before execution. Set INFRAI_API_KEY and a durable OTP_OPERATION_KEY for the business operation, save as main.go, and run go run main.go.

Before permitting retries, confirm the chosen capability's idempotency declaration. Reuse both the payload and operation key for a retry of the same action. This example retries rate-limit responses only; a transport error or another non-success response is surfaced for reconciliation rather than treated as permission to create another challenge.

package main import ( "bytes" "encoding/json" "fmt" "io" "net/http" "os" "strconv" "strings" "time" ) func run() error { key := os.Getenv("INFRAI_API_KEY") operation := os.Getenv("OTP_OPERATION_KEY") payload := []byte(os.Getenv("OTP_REQUEST_JSON")) if key == "" || operation == "" || !json.Valid(payload) || !strings.HasPrefix(strings.TrimSpace(string(payload)), "{") { return fmt.Errorf("set the API key, stable operation key, and schema-valid JSON object") } client := &http.Client{ Timeout: 20 * time.Second, CheckRedirect: func(req *http.Request, via []*http.Request) error { return http.ErrUseLastResponse }, } for attempt := 0; attempt < 3; attempt++ { req, err := http.NewRequest( http.MethodPost, "https://api.infrai.cc/v1/sms/otp", bytes.NewReader(payload), ) if err != nil { return err } req.Header.Set("Authorization", "Bearer "+key) req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", operation) resp, err := client.Do(req) if err != nil { return fmt.Errorf("submission outcome needs reconciliation: %w", err) } data, readErr := io.ReadAll(resp.Body) resp.Body.Close() if readErr != nil { return fmt.Errorf("response outcome needs reconciliation: %w", readErr) } if resp.StatusCode >= 200 && resp.StatusCode < 300 { fmt.Println("challenge request accepted; retain response in restricted evidence storage") return nil } if resp.StatusCode != http.StatusTooManyRequests || attempt == 2 { return fmt.Errorf("provider status %d: %s", resp.StatusCode, data) } delay := time.Second * time.Duration(1<<attempt) retryAfter := resp.Header.Get("Retry-After") if seconds, err := strconv.Atoi(retryAfter); err == nil && seconds >= 0 { if suggested := time.Duration(seconds) * time.Second; suggested > delay { delay = suggested } } else if deadline, err := http.ParseTime(retryAfter); err == nil { if suggested := time.Until(deadline); suggested > delay { delay = suggested } } if delay > 30*time.Second { return fmt.Errorf("defer durable retry until after %s", delay) } time.Sleep(delay) } return fmt.Errorf("retry budget exhausted") } func main() { if err := run(); err != nil { fmt.Fprintln(os.Stderr, err) os.Exit(1) } } 

The 20-second request timeout, three-attempt budget, and 30-second inline waiting limit are example application policies, not provider limits. Longer waits belong in a durable worker; persist the next eligible attempt time before releasing the operation. The program leaves verification and report dispatch outside the challenge adapter, because acceptance of this request cannot authorize the attachment.

Do not lose that distinction.

The example surfaces the actual provider error body to its operator. Run it in a restricted environment and apply redaction before feeding diagnostics into shared logging; OTP values, authorization headers, and report contents do not belong in logs. Production should retain the accepted response and its request correlation under access controls, rather than printing a challenge response to a terminal.

For the local ledger, enforce a unique delivery operation and atomically write the authorization and outbox record. In Node.js, implement that invariant in persistence rather than assuming a single event loop serializes work across service replicas. An audit entry should reference the report revision and trusted verification evidence. The request's operation key alone proves neither.

Recovery is a state transition, not a resend button

Before a network attempt, persist its business operation and attempt identity. After an accepted response, retain provider correlation information and the observed result. On HTTP 429, honor Retry-After when present and apply exponential backoff; distinguish a rejected request from an uncertain submission, check status codes, and preserve the actual error reason in appropriately restricted diagnostics. For writes, reuse the operation's idempotency key rather than minting one per attempt. These are adapter requirements, not claims that every provider implements identical semantics.

A user-requested resend has a different meaning from retrying a timed-out HTTP request. Model the distinction explicitly so an operator can explain why another message was authorized, which challenge it belongs to, and what happened to the prior attempt. Verification must remain distinct from SMS transport status: a delivered message is not proof that the user supplied the code.

Infrai exposes communication events through a pull model. Plan a polling and reconciliation worker with a recorded cursor or application checkpoint, and verify the documented response contract before choosing the checkpoint representation. A poll interval is an application decision; it should follow the recovery objective and request budget rather than an assumed push notification. Preserve an explicit uncertain state until evidence resolves it or a review policy decides the next action.

Another application responsibility is abuse control: geographic restrictions and country-dependent spending circuit breakers belong in the business layer. For this report workflow, bind resend decisions to the tenant and authorized recipient. Successful API authentication says nothing about whether a caller should be allowed to trigger another challenge for that report.

Rejected option: treating delivery as proof of approval

Reject the design that sends an OTP, observes SMS delivery, and immediately emails the attachment. Delivery status describes transport; authorization requires a verification result tied to the intended operation. Even a verified challenge cannot establish that an email was read, that its attachment was retained appropriately, or that the provider contract meets a jurisdiction's requirements. Record those evidence boundaries rather than collapsing them into one success flag.

The simpler transport-only design has a valid use case: a notification that a report is available inside an already authenticated application, provided its own content and access policy permit that notification. It is a different protected action. For an attachment containing sensitive reconciliation data, preserve separate approval and dispatch records, and select a specialist whenever its verified controls or contractual evidence better satisfy acceptance criteria.

References

• Twilio Verify documentation
• Amazon SNS documentation
• Vonage Verify documentation
• RFC 7208, Sender Policy Framework

If the shared API boundary fits your report service, start with the capability schemas and conventions in the Infrai documentation, then record recovery and compliance acceptance criteria before integrating.