DEV Community

MaximilianNilsson7568
MaximilianNilsson7568

Posted on

Template Revision Binding for SMS OTP Endpoint and Direct Send API Verification

Keep signup verification templates under application release control, and choose the sending interface according to who must own challenge validation. For an edtech account signup, the immediate job is to deliver a verification link; an SMS login code and an authenticator app belong to related authentication decisions, but neither should silently change what that link proves.

Short answer: Direct sending gives the application control over message rendering and makes it responsible for verification state. A dedicated OTP endpoint can delegate that lifecycle only to the extent its documented contract supports it. Compare template ownership, token consumption, and account activation before selecting a simple SMS API for a 2FA auth flow.

Consider a proposed signup flow for a learning platform: a learner submits an email address, receives a link, and follows it to confirm that address. The useful design question is what happens when a template changes while a message waits for delivery, or when the same link is presented twice. A successful send cannot answer either question. A cheap transport doesn't establish a safe state transition.

What does the signup link actually prove?

The decision record starts with a narrow assertion: this application treats successful consumption of its challenge as confirmation of the address bound to that challenge. It must not turn an email delivery acknowledgment into account activation, or describe address confirmation alone as two-factor authentication. The latter requires a separate authentication design; adding a second message does not establish an independent factor.

For this proposed system, the invariants are explicit. A challenge belongs to one pending account and one destination snapshot. Its purpose is signup verification. It has a server-enforced expiration, can transition to consumed once, and cannot activate a different account if a browser supplies a different account identifier. The transition that consumes it and the transition that verifies the address must commit together. These are design requirements, not promises about an unspecified messaging service.

Delivery is separate.

That separation matters to a storage architect because the database can commit while a process stops before contacting the sender, and a sender can accept a request before the application records its response. A proposed transactional outbox places a delivery intent beside the challenge in the same database transaction. It makes the intent recoverable; it does not make an external side effect atomic with that transaction. Name the remaining boundary honestly: duplicate delivery after an uncertain acknowledgment.

RFC 7208 describes SPF authorization of hosts sending mail for a domain. That is useful transport evidence, but it does not specify application token consumption, learner identity, or a transaction that verifies an account. Keep those claims separate in the design review.

How should an auth app compare direct SMS send with an OTP endpoint?

The primary decision is who can change what the learner sees, and how that change becomes associated with a particular challenge. For the proposed platform, store an immutable template revision with the delivery intent, along with the locale, destination snapshot, purpose, and challenge reference. A revision label is useful only if its content remains retrievable: updating a mutable template behind an unchanged label destroys the evidence the label was supposed to preserve.

There are 3 separate responsibilities to assign: rendering, challenge validation, and account activation. A single endpoint may cover several of them, but an endpoint name is insufficient evidence.

Read its contract.

Proposed option Template ownership Verification responsibility Boundary to establish before adoption
Application-rendered signup link through direct delivery Application pins the revision and renders the link Application validates and consumes its token Delivery acceptance must remain separate from address verification
Application-rendered SMS code through direct send Application owns wording and code placement Application owns issuance, expiry, attempt limits, and consumption Sending alone supplies no challenge-validation contract
Dedicated OTP service Depends on documented template and localization controls Service validates the challenge within its documented scope Determine how a verification result binds to the pending account and intended purpose
Authenticator app using TOTP No outbound SMS template for generating that code Verifier checks the enrolled shared-secret credential Enrollment, replay handling, and recovery need their own design; a generated code does not deliver a signup link

This comparison describes responsibility assignments, not feature claims about products. A service with delegated verification can still be a poor fit if the learning platform needs to reproduce the exact signup text approved for a particular locale and the service cannot document how template revisions are selected. Conversely, full rendering control has little value if the application team cannot operate the challenge store responsibly.

The tempting shortcut is to select a generic SMS sender because its example is short. That moves validation work into the application; it doesn't remove it. A request for a simple SMS API example, including one written for a JavaScript backend, therefore needs a lifecycle decision before a language-specific HTTP call. The Python example below makes that boundary visible without prescribing a commercial transport.

Put the critical transition behind a durable contract

The following code is an interface sketch for the proposed service, not a working messaging integration. The repository implementation must enforce the transaction and concurrency contracts in its method documentation. Keeping those obligations explicit is more useful than an example that returns success after placing a message on a queue.

from dataclasses import dataclass
from datetime import datetime
from typing import Protocol


@dataclass(frozen=True)
class SignupIntent:
    account_id: str
    destination: str
    locale: str
    template_revision: str


class SignupRepository(Protocol):
    def issue_with_outbox(self, intent: SignupIntent) -> None:
        """Atomically persist a challenge and its delivery intent.

        Generate an unpredictable token; store its verifier and expiry.
        Bind the challenge to the pending account and destination.
        Put the link in a protected outbox payload for delivery.
        """
        ...

    def consume_and_verify_address(
        self, token: str, now: datetime
    ) -> bool:
        """Validate and consume the token in one transaction.

        Require signup purpose, an unexpired and unconsumed challenge,
        and a still-matching pending account and destination.
        Atomically consume it and mark that address verified.
        Concurrent consumption must permit at most one success.
        """
        ...


def request_signup_link(repo: SignupRepository) -> None:
    repo.issue_with_outbox(
        SignupIntent(
            account_id="pending-learner-42",
            destination="learner@example.org",
            locale="en-US",
            template_revision="signup-link-r3",
        )
    )


def confirm_signup(
    repo: SignupRepository, token: str, now: datetime
) -> bool:
    return repo.consume_and_verify_address(token, now)
Enter fullscreen mode Exit fullscreen mode

The account identifier, locale, and revision are illustrative application data. They are not API parameters claimed for an external service. In a real request handler, the pending account and its destination would come from validated application state. The confirmation path accepts the token rather than a caller-selected account identifier, leaving account resolution inside the repository's verification transaction.

A subtle storage trade-off appears at issuance. A verifier suitable for checking a submitted token is not necessarily enough to reconstruct the original link after a worker restarts. If asynchronous delivery needs the original token, the proposed outbox must retain a protected delivery payload until that work is complete. Treat that payload as credential material: restrict access, exclude it from ordinary logs, and define deletion and backup-retention policies. A statement that only token hashes are stored would be misleading if the full link remains in an outbox or archive. Consider the proposed learner account in the example: its challenge row might contain only a verifier, while a queued email contains the complete credential-bearing link. Removing the queue item after delivery would address the live copy, but a database backup taken before that removal could still contain it. The retention decision therefore needs to cover recoverable copies as well as the active table, while expiration must remain enforced at consumption even if an old payload is later restored.

Then specify what requesting another link means.

One defensible policy is to create a new challenge and invalidate older pending challenges for the same account and purpose; another is to reuse the current valid challenge. Either requires a deliberate transaction rule. Without one, delivery order can decide which link appears current, and a learner who opens an older message gets behavior the support team cannot explain.

Test the boundaries that a send receipt cannot establish

The acceptance tests should target state transitions. Submit one token concurrently and require exactly one successful consumption. Move the test clock past its configured expiration and require rejection. Change the pending destination before consumption and require the earlier challenge to fail. Interrupt a delivery worker after external acceptance but before acknowledgment, then confirm that replaying its work cannot verify an account. These are proposed tests, not reported production results.

A template deployment needs its own check: enqueue an intent using revision r3, release r4, and verify that the queued message still renders r3. Otherwise the revision column is theater. The rollback procedure should preserve the ability to render already-issued intents, or explicitly cancel and replace them under the documented reissuance policy.

Logs need restraint.

Record a correlation identifier, template revision, challenge state transition, delivery attempt outcome, and an application reason category for rejection. Exclude raw links, codes, and destination addresses from routine event payloads. Measure the path from issuance to confirmed address separately from sender acceptance, because combining those events hides whether learners are actually completing signup. Define retention against support needs and the sensitivity of the retained records, rather than letting a queue's default history become the credential archive.

For an SMS alternative, MDN documents WebOTP as a browser API for retrieving specially formatted OTP messages and notes its limited availability and secure-context requirements. Treat it as progressive enhancement. It does not replace server validation, and a browser convenience feature does not supply the missing challenge store. Keep manual code entry available wherever that flow is supported.

Operational effort is part of the decision: application-owned rendering adds review and localization work, while application-owned verification adds abuse controls, expiry handling, and recovery obligations. Count those responsibilities before making price the deciding criterion. No unit-price comparison can establish who owns a missing state transition.

Rejected option and the conditions that would change the decision

For this proposed signup flow, reject moving the entire process to an OTP endpoint solely to shorten the send handler. The job is delivery of a verification link with reproducible application-owned text, followed by an atomic account-state transition. An undocumented assumption that an endpoint owns all of that is too weak a basis for the decision.

Delegated OTP verification remains a valid choice for a code-entry flow if its documented template controls, expiration behavior, attempt policy, result binding, and reissuance semantics meet the application's requirements. The application still needs to decide how verified results affect its own account state. If those contracts are clear and the team accepts the template boundary, delegation can reduce the challenge machinery it must operate.

An authenticator app is a separate valid choice for an enrolled authentication factor. RFC 6238 specifies time-based one-time passwords and discusses validation windows and replay handling; it does not turn TOTP enrollment into confirmation that a learner received a signup email. Design enrollment and recovery explicitly before offering that path.

The decision stands until the interface contract or the signup requirements change: own the template revision, preserve the delivery intent durably, and make successful token consumption the event that verifies the bound address. A send receipt is useful evidence about delivery processing. Its authority ends there.

References

Top comments (0)