Short answer: choose the SMS OTP API whose message templates, retry policy, and regional sender rules your team can own and test; the fastest integration is useless if a marketplace support login silently routes users into an unreviewed template change.
I build CLIs and SDKs, so my first test is boring: can I make one verified request with one small TypeScript file? For a marketplace contact form that routes cases to the right support queue, the important boundary is template ownership. The OTP service should deliver the code, while your application owns the wording, locale, expiry, and the decision to retry.
The choice matrix I use
| Approach | Template owner | Retry and limits | Best fit | Trade-off |
|---|---|---|---|---|
| Hosted verification flow | Provider | Mostly provider | Tiny team, fixed copy | Less control over locale and queue context |
| Messaging API plus app logic | Your team | Your team | Marketplace with changing queues | More code and monitoring |
| Self-hosted gateway | Your team | Your team | Strict network or data rules | Carrier operations become your job |
My default is the middle row. It leaves the support queue and template in your repository, where a pull request can review them. It also keeps the provider swappable. That is a design decision, not a vendor endorsement.
What should a Node.js SMS OTP API expose for SaaS login?
Start with a narrow interface. send creates a challenge, verify consumes it, and a status value explains whether the caller may retry. Do not let a provider SDK leak into every route handler.
type Challenge = {
id: string;
phoneE164: string;
expiresAt: number;
attempts: number;
};
interface OtpTransport {
send(challenge: Challenge, body: string): Promise<{ messageId: string }>;
verify(challengeId: string, code: string): Promise<"approved" | "denied" | "expired">;
}
export async function requestLoginCode(
transport: OtpTransport,
phoneE164: string,
template: string,
): Promise<string> {
const challenge: Challenge = {
id: crypto.randomUUID(),
phoneE164,
expiresAt: Date.now() + 5 * 60_000,
attempts: 0,
};
await transport.send(challenge, template);
return challenge.id;
}
The five-minute value is an example policy, not a universal rule. Store only a hash of the OTP, bind it to the login attempt, and make verification single-use. NIST's guidance treats SMS as a restricted authenticator, so offer a stronger factor for accounts with sensitive seller or payout permissions.
Five checks before routing a contact form
Can a template change be reviewed? Keep
support_queue, locale, and expiry placeholders in versioned files. A queue label belongs to the marketplace application, not to an opaque dashboard. Render the final text in a test for US and EU numbers before sending.Does retry mean resend or re-verify? A resend should create a fresh challenge and invalidate the previous code. A wrong code should consume an attempt without sending another message. I once treated both paths as the same operation; a burst of HTTP
429responses followed, and the only useful clue was a request ID in the log.Are limits layered? Apply per-phone, per-account, per-IP, and per-device limits. Use a token bucket or sliding window in a shared store so two API instances cannot each approve a separate burst. Return a generic response for unknown accounts; otherwise the login form becomes a phone-number oracle.
Can US and EU delivery be observed separately? Record provider-independent events: challenge created, send accepted, delivery callback, verify approved, verify denied, and expiry. Keep phone numbers redacted in application logs. Compare latency and failure rates by country, carrier class, and template version.
What happens when the queue changes? Persist the intended support queue with the challenge. The verification callback should not look up a mutable default and accidentally send a seller to buyer support. If the queue is no longer valid, fail closed and ask for a new login attempt.
Small details matter. A two-line event schema has saved me more debugging time than a larger SDK ever did.
Keep backoff outside the transport. The caller can then apply the same policy to different gateways and test it without network calls.
const RETRYABLE = new Set(["timeout", "temporarily_unavailable"]);
export async function sendWithBackoff(
send: () => Promise<void>,
classify: (error: unknown) => string,
maxAttempts = 3,
): Promise<void> {
for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
try {
await send();
return;
} catch (error) {
const kind = classify(error);
if (!RETRYABLE.has(kind) || attempt === maxAttempts) throw error;
const delayMs = Math.min(2_000, 200 * 2 ** (attempt - 1));
await new Promise((resolve) => setTimeout(resolve, delayMs));
}
}
}
Never retry a rejected number or an invalid code. Those are user or policy outcomes, not transport failures. Add an idempotency key to the send operation so a timeout does not produce two messages with different codes.
The long tail is template rollback. Imagine a marketplace deploy that changes “Your code for seller support” to a generic “Your code,” then a second deploy changes the EU translation but leaves the US fixture untouched. A login test can still pass while a support agent loses the queue hint. Store a template version beside each challenge, emit it in delivery events, and keep the previous version available for one release window. A rollback then changes a pointer, not a live dashboard setting. This is also why I keep the transport interface tiny: a fake transport can capture the exact body, locale, queue, and idempotency key in a unit test. The test should assert that a resend invalidates the old challenge, that an expired challenge cannot be approved, and that a provider timeout schedules one bounded retry. None of those assertions require a real phone or a paid message.
When is the runner-up a better fit?
The hosted flow wins when you have no appetite for message rendering, callback verification, or regional sender registration. Pick it when a fixed template is acceptable and the provider's audit trail satisfies your requirements.
The catch is ownership. It is not suitable when support agents need queue-specific copy, when legal review requires every locale in your repository, or when your team must replay a deterministic test. In those cases, keep the application-owned template and use a lower-level messaging API or a self-hosted gateway, accepting the extra operations work.
Your mileage may vary on delivery latency; carrier filtering changes by country and sender type. Measure it with synthetic numbers and real delivery callbacks instead of trusting a dashboard average. I am not sure any single API can hide those regional differences.
Top comments (0)