#SMS One-Time Code (SMS OTP)
SMS one-time code is an optional second factor for portal sign-in. It is restricted to client_admin and partner_admin accounts and is only available when your organisation has been opted in by an AiDial operator. The feature is deny-by-default unless the current tenant's mfa.sms_otp.enabled flag is enabled.
#What it is
When SMS OTP is enrolled, Zitadel sends a one-time code by text message during sign-in. You enter the code on the Zitadel sign-in screen to complete the second factor. AiDial Portal does not collect or validate SMS code values itself.
#How enrolment works
When the portal renders the SMS factor card on the profile/MFA security surface, it appears only if SMS one-time code is available for your role and organisation. The card shows the privacy notice and an Australian mobile-number field before enrolment.
The browser submits the phone number to the portal BFF route POST /api/auth/mfa-sms-enrol. The route enforces CSRF and session authentication, checks the role and tenant gates, validates the number, applies rate limits, and then calls Zitadel's SMS factor endpoint server-side. The browser does not send an X-API-Key.
On success, the response contains only a masked phone_tail such as +61 ... 678.
#Who can use it
| Role | Eligibility |
|---|---|
client_admin | Yes (when the organisation override is enabled) |
partner_admin | Yes (when the organisation override is enabled) |
client_manager, client_staff, partner_user | Not available — use authenticator app (TOTP) |
aidial_admin, aidial_operator | Not available — use authenticator app (TOTP) |
#Privacy Notice (APP-5)
By enrolling SMS one-time code, you consent to AiDial Pty Ltd disclosing your mobile number to Twilio Inc. (United States) — our authentication SMS sub-processor — for the sole purpose of delivering security codes. Twilio handles this data outside Australia. You may withdraw consent by removing SMS one-time code through the identity-provider management flow launched from Settings when available.
#What we store
| Surface | What we hold |
|---|---|
| Portal session/JWT | MFA factor identifiers and state only; no full phone number and no persisted phone tail |
| SMS enrolment response | Masked phone tail (+## ... 999) only |
| Portal database | No SMS OTP phone-number table or SMS factor copy; audit events only |
| Portal audit log | Factor, outcome, request metadata, and masked phone tail when available |
| Browser local storage | Nothing; the masked tail is held only in the current page state after enrolment |
| Zitadel identity store | Full phone number as the SMS authentication factor |
| Twilio | Phone number + delivery status only |
The portal briefly receives the phone number once at enrolment time so it can validate the country prefix, derive SHA-256 hashes for rate-limit buckets, and forward the number to Zitadel. The plaintext is discarded after the Zitadel call. Zitadel holds the canonical SMS factor record; the portal's later enrolled-factor lookup reads only factor presence, not the full phone number or phone tail.
SMS enrolment audit metadata is passed through the MFA audit redactor. Full phone-number keys, raw OTP values, recovery codes, session tokens, cookies, and bearer headers are stripped before audit emission.
#Supported phone numbers
- Australia (
+61) only. - Non-Australian E.164 numbers are rejected before the portal calls Zitadel.
#Delivery failures and carrier opt-out
If SMS delivery is blocked, the enrolment flow can surface a delivery/provider warning. If you previously replied STOP, the carrier may block future SMS delivery. Use a different second factor, such as an authenticator app or recovery code, or update/remove the SMS factor through the provider management flow when available.
#What we do not do
- We do NOT send marketing or promotional SMS.
- We do NOT send appointment reminders, booking confirmations, or other business-flow SMS through this surface. Those use a separate Twilio configuration in the AiDial voice runtime.
- We do NOT use SMS OTP for any AiDial voice or chat runtime.
- We do NOT share your phone number with any third party other than the identity-provider/SMS delivery path described above.
#Removing SMS OTP
Use the MFA management action in Settings Profile & Security or Account > Security when a trusted provider management or disable action is available. The portal opens the Zitadel management page in a new tab. The portal does not directly delete the SMS factor; complete removal in Zitadel, then return to the portal and refresh your security status.
#Troubleshooting
- "SMS one-time code is not available for this organisation": your organisation has not opted in. Contact your administrator.
- "SMS one-time code is not available for this account type": your role does not allow SMS OTP. Use authenticator app (TOTP) or recovery code.
- "Only Australian phone numbers are supported": AiDial supports
+61numbers only at launch. - "Too many SMS one-time code requests": the rate limit has been reached. The portal enforces per-phone and per-user buckets (3 per minute and 10 per day), a trusted source-IP bucket when proxy headers are verified (30 per hour), and a global bucket (100 per minute). Wait one minute and try again.
- "We could not deliver the SMS to this number": the provider was unavailable or the carrier may have blocked delivery. Update your number through the provider management flow when available, or use a different second factor.
- "SMS OTP provider is not configured": the identity-provider SMS integration is unavailable. Use another second factor and contact support.
#Operator runtime dependencies
This flow depends on the portal's standard required runtime configuration: NEXTAUTH_SECRET, NEXTAUTH_URL, AIDIAL_API_BASE_URL, AIDIAL_API_TIMEOUT_MS, ZITADEL_ISSUER, ZITADEL_CLIENT_ID, and ZITADEL_CLIENT_SECRET. These values are required; the portal code does not define fallback defaults for them.
SMS enrolment also requires the identity-provider SMS factor creation integration to be configured. If that integration is unavailable, POST /api/auth/mfa-sms-enrol fails closed with mfa_sms_provider_unavailable.
#Sub-processor disclosure
| Sub-processor | Country | Purpose | Data shared |
|---|---|---|---|
| Twilio Inc. | United States | Deliver authentication SMS | Mobile number + delivery status |
| (See multi-factor-auth.md for the email OTP sub-processor disclosure) |