Implementing SMS Two-Factor Authentication with Twilio Verify API

The Problem: Managing 2FA Complexity

Building a custom two-factor authentication (2FA) system requires managing code generation, expiration timers, rate limiting, and delivery across global carriers. The Twilio Verify API abstracts this complexity by handling the entire lifecycle of the one-time passcode (OTP), allowing developers to focus on the user experience rather than the backend logic of secret management.

Prerequisites

• A Twilio account with an active API Key and Secret.
• A Service SID (created via the Twilio Console under Verify > Services).
• An HTTP client (such as cURL) or a backend environment capable of making POST requests.
• A destination phone number in E.164 format (e.g., +15551234567).

Implementation Procedure

1. Trigger the Verification Code

To initiate the process, send a request to the Verifications resource. This tells Twilio to generate a code and deliver it to the user via the specified channel.

# Run this from your secure backend server
curl -X POST "https://verify.twilio.com/v2/Services/{{SERVICE_SID}}/Verifications" \
  -u "{{API_KEY_SID}}:{{API_KEY_SECRET}}" \
  -d "To=+15551234567" \
  -d "Channel=sms"

Required Permissions: The API Key used must have permissions to access the Verify API resources.

Expected Result: A JSON response containing a sid (the unique identifier for this specific verification attempt) and a status of pending.

Risk: Carrier filters may block SMS messages if the destination number is flagged as spam. If the response indicates a failure, consider providing the user an alternative channel, such as call or email.

2. Validate the User-Provided Code

Once the user receives the SMS and enters the code into your application, you must verify that the code is correct and has not expired.

# Run this from your secure backend server
curl -X POST "https://verify.twilio.com/v2/Services/{{SERVICE_SID}}/Verifications/{{VERIFICATION_SID}}/Check" \
  -u "{{API_KEY_SID}}:{{API_KEY_SECRET}}" \
  -d "Code={{USER_SUBMITTED_CODE}}"

Key Placeholders: Replace {{VERIFICATION_SID}} with the SID returned from the initial trigger request and {{USER_SUBMITTED_CODE}} with the digits entered by the user.

Expected Result:

• Success: The response returns status: "approved".
• Failure: The response returns status: "pending". An incorrect code typically triggers error code 20404.

3. Secure the Callback Flow

If you use status callbacks to monitor delivery, you must verify that the incoming request actually originated from Twilio to prevent spoofing attacks.

• Capture the X-Twilio-Signature header from the incoming request.
• Recompute the HMAC-SHA1 signature using your Auth Token and the full URL of the request.
• Compare your computed signature with the header; if they do not match, discard the request.

Verification and Testing

To verify the implementation without consuming paid credits or risking carrier blocks:

1. Use Test Credentials: Use Twilio's test API keys to simulate the flow. In test mode, the API will not send a real SMS but will return a successful response.
2. Simulate Code Entry: In test mode, the code 000000 is typically accepted as valid. Check that your application correctly transitions to the "approved" state.
3. Audit Logs: Review the Verify > Services > [Your Service] > Logs section in the Twilio Console to ensure requests are being processed and that no unauthorized attempts are occurring.

Limitations and Considerations

Factor	Detail
Cost	Billed per attempt (approx. $0.0075 for US SMS as of 2024-2025).
Visibility	The raw OTP is never returned in the API response for security; only the Check endpoint can validate it.
Delivery	SMS delivery is subject to local carrier regulations and may be delayed.