March 01, 2024
Send domain-bound one-time passcodes with Twilio Verify
Domain-bound one time passcodes (OTPs) help prevent SMS phishing by restricting where codes will autofill to your legitimate, authorized domain. This is a simple and useful upgrade to an existing SMS OTP workflow to help keep your customers secure. Phishing attacks rely on the attacker successfully tricking the user into interacting with a fake domain, but domain-bound codes increase the friction required to enter the OTP, making it harder for attackers to succeed
The format of the messages is standardized with the support of Apple and Google :
123456 is your Example code.
@example.com #123456
You can customize the wording of the first line, but domain-bound codes (sometimes referred to as origin-bound codes) must include the second line with the @domain and #code. The Twilio Verify API supports domain-bound codes with templates .
Prerequisites for sending domain-bound codes with Twilio Verify
To start sending OTPs with Twilio Verify you will need:
- A free Twilio Account - sign up or sign in
- A Verify Service SID - create one in the Twilio Console
- A custom Verify template - read on for detailed instructions
Learn about the variety of benefits you get from using Twilio Verify API .
Request a custom Verify template with your domain
You can request a custom Verify template by contacting the Twilio Support team with the following information:
- Your Account SID
- Your Verify Service SID
- The message body you want to register, which will look like:
{{code}} is your {{friendly_name}} code.
@yourdomain.com #{{code}}
- The name you want to assign to the custom template
- The locale. Include if the locale is going to be used as default ( see example here )
- Confirm if the template will be used to send traffic to Canada, Singapore, Malaysia or China
Canada, Singapore, Malaysia, and China may have additional regulatory requirements for registering Sender IDs . Support will work with you to make sure you are compliant.
Support will walk you through any edge cases. Once support verifies your template you can approve it and manage templates in the console.
Send a verification code with your custom template
After support creates your template, you can set a default template for a Verify Service in the Console (under the “General” tab of your Verify Service) or with the API:
curl -X POST https://verify.twilio.com/v2/Services \
--data-urlencode "FriendlyName=My Verify Service" \
--data-urlencode "DefaultTemplateSid=HJXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
Alternatively, you can set the template when you start a verification:
curl -X POST https://verify.twilio.com/v2/Services/VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Verifications \
--data-urlencode "To=+15017122661" \
--data-urlencode "Channel=sms" \
--data-urlencode "TemplateSid=HJXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
Add domain-bound autofill from your application front end
To take full advantage of domain-bound codes, add the autocomplete="one-time-code" to your OTP <input>. Reference the documentation for adding autofill support in iOS native apps or for supporting the WebOTP API on Android devices.
Other customization options for Twilio Verify
This upgrade will help keep your users more secure and provide a better authentication experience where available. Now that you’ve implemented autofill, you can further customize your Verify implementation with other template options.
Check out these additional resources to make sure you’re getting the most out of your OTP workflow:
- How to Validate Success of your Verify Implementation
- How to detect a SIM Swap before sending an SMS OTP
- Best practices for multi-factor authentication account recovery
I can’t wait to see what you build and secure.