--- sourceDocument: Australia Platform security sourceDocumentLink: https://www.servicenow.com/docs/r/australia/platform-security Release : - australia ft:locale : - en-US ft:publication_title : - Australia Platform security ft:clusterId : - psec bundleId : - psec workflow : - Platform --- # Configure human-assisted SMS OTP # Configure human-assisted SMS OTP {#ariaid-title1} Release version: Australia Updated November 5, 2026 ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 3 minutes to read Configure the HA SMS OTP service to enable human agents to generate and validate one-time pass codes during live interactions. ## Before you begin Role required: `sn_auth_ha_sms_otp_admin` Perform the following: * Install the HA SMS OTP plugin (`sn_auth_ha_sms_otp`). This also installs the dependent Multi-factor authentication with SMS plugin (`com.snc.authentication.sms_mfa`) if not already present. * Enable human-assisted SMS OTP using the `glide.auth_factors.ha_sms_otp.enabled` property. Set it to `false` to turn the feature off; the default is `true`. Read and write access to this property is restricted to users with the `sn_auth_ha_sms_otp_admin` or `security_admin` role. * For OOB delivery mode: configure an SMS provider (Twilio, Infobip, or Custom) under AllMulti-factor AuthenticationProviders. To know more, see [SMS One-time passcode (OTP) authentication](https://www.servicenow.com/docs/B1ZbdsvzMPF5Pis2R8HMJw "SMS one-time password (OTP) authentication is a method used to verify user identity by sending a temporary, numeric code to the user's registered mobile number. The user enters this code to complete authentication.") for provider setup instructions. * Grant the `sn_auth_ha_sms_otp_caller` role to any user or integration that will call the HA SMS OTP API. * Grant the consuming application scope explicit permission to execute the HA SMS OTP API methods. ## Procedure 1. Navigate to All \> Authentication Factors \> Human-Assisted SMS OTP \> Configuration. 2. Select an existing configuration record to edit, or select New to create one. Figure 1. Human Assisted SMS OTP Service Configuration list view 3. Fill in the following fields. Figure 2. Human Assisted SMS OTP Service Configuration {#configure-human-assisted-sms-otp__steps__entry__3} | Field | Description | Default | |-|-|-| | Name | Label for this configuration (for example, HR Helpdesk SMS OTP). | Default HA SMS OTP | | Global User Retry Window (days) | The rolling time window, in days, over which a user's OTP retry attempts are counted. Attempts made within this window accumulate toward the user's retry limit; once the window elapses, the count resets. | 7 (range: 1 to 30) | | Global User Lockout Duration (days) | The number of days a user is prevented from requesting further OTPs after exhausting their allowed retry attempts. | 1 (range: 1 to 15) | | Active | When unchecked, this configuration is skipped at runtime. If no active configuration exists, OTP requests fail. Note: Only one active record can exist per domain. | true | | Delivery Mode | * OOB: the platform sends the SMS via the configured provider. * BYO: the platform generates and validates the OTP; the consuming application handles delivery. | OOB | | Phone Number Resolution | How the platform resolves the end user's phone number for OOB delivery. * Provided by calling application: phone number is passed in the API request. * Resolved from configured table: platform looks up the phone from the table and column configured below. Applies to OOB only. | Config-table lookup | | Phone Table | Table used to look up the end user's phone number (for example, `sys_user`). Used with config-table lookup only. | --- | | Phone Column | Column on the Phone Table that stores the phone number in E.164 format (for example, `mobile_phone`). Used with config-table lookup only. | --- | | User Column | Column on the Phone Table used to match the end user to a record (for example, `sys_id`). Used with config-table lookup only. | --- | | OTP Code Length | Number of digits in the generated OTP. | 6 (range: 6 to 8) | | OTP Expiry (Minutes) | Minutes before an unverified OTP expires and a new one must be requested. | 3 (range: 1 to 10) | | Per-Conversation User Retry Limit | Maximum incorrect validation attempts per conversation. Counts failed validateCode calls only. Triggering a resend does not consume this budget. | 3 (range: 1 to 10) | | Resend Cooldown (seconds) | Minimum seconds between consecutive OTP generation requests within the same conversation. | 60 (range: 0 to 600) | | Global User Retry Limit | Maximum failed OTP verification attempts for a single end user within the configured retry window. When exhausted, the user is locked out for the configured lockout duration, after which the counter resets. | 10 (range: 1 to 100) | | Rate Limit Per Minute Per Agent | Maximum OTP requests a single agent can trigger per minute. Set to 0 to disable. | 10 (range: 0 to 100) | | Rate Limit Per Minute Per Tenant | Maximum OTP requests across all agents in the tenant per minute. Set to 0 to disable. | 100 (range: 0 to 1000) | | Domain | Domain this record belongs to. Controls visibility in domain-separated instances. | --- | [ ] Note: If Delivery Mode is set to OOB and your SMS provider is a Custom type, phone number resolution uses the table and field configured in your MFA Provider Custom config record, not the Phone Number Resolution selection. In case of a mismatch, the MFA Provider Custom config takes precedence. 4. Select Submit. {#configure-human-assisted-sms-otp__steps} ## Result The HA SMS OTP service configuration is active and available for use by the consuming application's scriptable API calls. The consuming application can now call generateCode and validateCode to authenticate end users during human-assisted interactions. **Related concepts** * [Human-assisted SMS OTP authentication](https://www.servicenow.com/docs/AEDAD1Gx0SVnv5YjXKte1g "Human-assisted SMS OTP lets a human agent verify an end user's identity by sending a one-time passcode via SMS during a live interaction. The agent initiates OTP generation and validation through the platform's scriptable APIs, and the consuming application (for example, CSM or FSO workspace) handles the agent-facing workflow and user interface.") * [SMS One-time passcode (OTP) authentication](https://www.servicenow.com/docs/B1ZbdsvzMPF5Pis2R8HMJw "SMS one-time password (OTP) authentication is a method used to verify user identity by sending a temporary, numeric code to the user's registered mobile number. The user enters this code to complete authentication.") * [Configure authentication factors for AI voice agents](https://www.servicenow.com/docs/beBiwnUoZfSUJbCPFuwWfw "To secure voice agent environments, configure authentication factors that first identify the caller, then authenticate them before granting access.") *[\>]: and then