Confirm access with a phone code

A verified phone displays a one-time code beside a clock and confirmation mark.

Confirm access with a phone code

Offer a short-lived code sent to a verified phone when that method fits the account policy. Wildo connects phone verification, delivery limits and code checking to the normal authentication flow.

You choose where SMS is enabled and configure a delivery provider. Verifying a phone number and signing in with it remain separate actions.

Example — Use an enrolled phone as a second step

A member first proves their primary credential, then receives a code on their verified phone. The code completes the enabled second-factor step.

For engineers

Establish the phone before using it as proof

Phone enrollment uses phoneVerifySend(phoneNumber) and phoneVerifyConfirm(phoneNumber, code). Confirmation persists the verified phone on the credential record. This enrollment action does not itself sign the person in.

Send and submit the authentication challenge

The standard SmsOtpAuthMethod.tsx receives an authentication sessionId and uses it for both steps. The send handler calls getManualCallsHttpClient().smsOTPSend(sessionId); it does not let the person substitute an arbitrary destination for their verified phone. The submit handler then continues that same authentication session:

const handleVerify = useCallback(async (data: SmsOtpChallengeFormDto) => {
  clearCodeFormError();
  try {
    const response = await handleMfaVerify(sessionId, AuthMethod.SMS_OTP, data.code.trim());
    if (response.success) {
      onSuccess(response);
    } else {
      setCodeFormError(response.error || t(MfaChallengeLabel.ERROR_INVALID_CODE));
    }
  } catch (e: any) {
    setCodeFormError(e?.message || t(MfaChallengeLabel.ERROR_INVALID_CODE));
  }
}, [sessionId, handleMfaVerify, onSuccess, t, clearCodeFormError, setCodeFormError]);

This is the existing frontend challenge handler, not a complete standalone component. handleMfaVerify comes from the authentication flow, while onSuccess hands its response back to the parent. Failed verification stays in the challenge form; a successful code follows the server’s authentication result.

Enable the method and wire the provider

Start with the SMS delivery setup: enable EngineCapability.SMS, select the backend Twilio provider, synchronize its artifacts, supply TWILIO_CREDENTIALS and configure the sender number. Keep the secret in the backend deployment environment. The provider guide contains the complete configuration fragments; choosing an authentication method does not perform those steps.

In backend-api/src/saas-config.backend.ts, merge this policy into the intended userTypes.<type>.auth. Import AuthMethod from @wildo-ai/saas-models; existingMemberAuth is that type’s existing complete policy:

const memberAuth = {
  ...existingMemberAuth,
  authMethodsEnabled: {
    ...existingMemberAuth.authMethodsEnabled,
    [AuthMethod.SMS_OTP]: true,
  },
};

SMS can be a first or second factor. This declaration enables the method; it does not require MFA or weaken an existing MFA requirement. For a password-then-SMS flow, password must also be enabled and the first credential must succeed before the SMS challenge completes the session. If SMS should qualify as a second factor, include AuthMethod.SMS_OTP in mfaPolicy.acceptableMFAMethods and check mfaPolicy.requireStrongMFA within the same user-type authentication policy. Keep the MFA policy consistent with the factors the application intends to accept.

Set the challenge window and sending budgets

Wonder Todos supplies the following backend operational settings under auth.otpOperational.smsOtp. These are explicit example values, not a claim that enabling SMS installs a provider or enrolls a phone. Merge this entry alongside the existing email-OTP settings:

smsOtp: {
  otpLength: 6,
  expiryMinutes: 5,
  rateLimitBurst: 1,
  rateLimitHourly: 5,
},

The burst and hourly limits apply to the resolved phone destination; the SMS-send controller also enforces its own source-IP limit. Increasing a phone budget does not remove the source-IP gate. The phone-enrollment challenge is a separate flow with its own checks; these settings describe authentication SMS codes.

Step	What must already be true	Observable result
Enroll the phone	The account can access the phone-verification flow and delivery is configured	Confirmation records the verified phone; it does not sign in
Request a sign-in code	The authentication session is in an eligible state and effective policy allows SMS	The provider accepts the submission, or the request fails
Submit the code	Use the same session and the received code within its validity window	Authentication advances according to the server response

An accepted send is not evidence that the handset received the message. Complete the challenge on a controlled account to verify the real delivery path. A missing or expired authentication session, exhausted budget or provider refusal must not be reported as successful delivery.

The SMS backend service uses the provider’s request builder and response parser, validates the standard result and refuses provider-reported send failures.

Authentication issuance resolves the verified target, checks effective policy and applies delivery budgets. An older outstanding code is revoked when a replacement is created. Verification uses the authentication session and advances the normal flow after a successful comparison.

Respect the customer’s identity authority

An actively directory-managed account has local SMS authentication disabled by the effective policy, just as local passwordless methods are disabled. The phone belongs to the person and is not a revocable IdP secret, so the method’s policy is the barrier. Choose stronger factors when the account’s requirements call for independent device proof; SMS availability is not a claim that every security policy should accept it.

Confirm access with a phone code