Verify TOTP: Change in API response when AuthPayload is incorrect

Summary

We'll be releasing two related breaking changes to the Verify TOTP API on October 27, 2021. These changes will improve the developer experience, before the feature enters the Public Beta maturity stage. They do not change the functionality of the feature. If you've written any implementation code that interfaces with the Verify TOTP API, including code that interfaces with the Twilio helper libraries, you'll need to update that code after the change. The following shows each change and an example of how your implementation code may need to change as a result.

Change #1

To verify a Factor, you need to send an API request that includes an AuthPayload containing a correct TOTP code provided by your end-user:

1curl -X POST https://verify.twilio.com/v2/Services/VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Entities/ff483d1ff591898a9942916050d2ca3f/Factors/YFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
2--data-urlencode "AuthPayload=293412" \
3-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Before the change

If the AuthPayload value is incorrect, the response is an error:

JSON response

1{
2    "code": 60311,
3    "message": "Factor verification failed",
4    "more_info": "https://www.twilio.com/docs/errors/60311",
5    "status": 403
6}

Example: Implementation code interfacing with Twilio Java helper library to handle this response

1try {
2    final Factor checkedFactor =
3          Factor
4                .updater(SERVICE_SID, IDENTITY, createdFactor.getSid())
5                .setAuthPayload("...")
6                .update();
7
8    // Factor is now verified...
9}
10catch (ApiException e) {
11    // Something happened. Check the error status code
12    if (e.getCode() == 60311) {
13        // Factor verification failed
14    }
15    else {
16        // Something else
17    }
18}

After the change

If the AuthPayload value is incorrect, the response is not an error. Instead, it is the same response as if the AuthPayload value were correct, except the status field remains "unverified" instead of changing to "verified."

JSON response

1{
2    "status": "unverified",
3    "friendly_name": "friendly_name",
4    ...
5}

Example: Implementation code interfacing with Twilio Java helper library to handle this changed response

1final Factor checkedFactor =
2      Factor
3            .updater(SERVICE_SID, IDENTITY, createdFactor.getSid())
4            .setAuthPayload("...")
5            .update();
6
7if (checkedFactor.getStatus() == Factor.FactorStatuses.VERIFIED) {
8    // Factor is now verified...
9}
10else {
11    // Factor verification failed
12}

Change #2

When updating a Challenge that is status:pending, you can include an AuthPayload containing the TOTP code provided by your end-user:

1curl -X POST https://verify.twilio.com/v2/Services/VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Entities/identity/Challenges/YCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
2--data-urlencode "AuthPayload=123456" \
3-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Before the change

If the AuthPayload value is incorrect, the response is an error:

JSON response

1{
2    "code": 60324,
3    "message": "Challenge verification failed",
4    "more_info": "https://www.twilio.com/docs/errors/60324",
5    "status": 403
6}

Example: Implementation code interfacing with Twilio Java helper library to handle this response

1try {
2    final Challenge checkedChallenge =
3          Challenge
4                .updater(SERVICE_SID, IDENTITY, createdChallenge.getSid())
5                .setAuthPayload("...")
6                .update();
7
8    // Challenge is now verified...
9}
10catch (ApiException e) {
11    // Something happened. Check the error status code
12    if (e.getCode() == 60324) {
13        // Challenge verification failed
14    }
15    else {
16        // Something else
17    }
18}

After the change

If the AuthPayload value is incorrect, the response is not an error. Instead, it is the same response as if the AuthPayload value were correct, except the status field remains "pending" instead of changing to "approved"

1{
2    "status": "pending",
3    "sid": "YC02...",
4    ...
5}

Example: Implementation code interfacing with Twilio Java helper library to handle this changed response

1final Challenge checkedChallenge =
2      Challenge
3            .updater(SERVICE_SID, IDENTITY, createdChallenge.getSid())
4            .setAuthPayload("...")
5            .update();
6
7if (checkedChallenge.getStatus() == Challenge.ChallengeStatuses.APPROVED) {
8    // Challenge is now verified...
9}
10else {
11    // Challenge verification failed
12}

Benefit & Impact

We are making these related changes because an incorrect AuthPayload is considered normal behavior resulting from users sometimes entering the wrong TOTP code, and not a bad API request or system issue that warrants an error. These changes should also make it easier for developers to interpret the response.

As shown in the previous Java examples, existing implementation code that expects the Before behaviors (a response that is an error) will likely break once the changes are made, so you should review and update. You don't need to update your Twilio helper library version for this change (although you can if you want to). These changes only affect Factors and Challenges of factortype:totp. They also do not affect the behavior of creating a new Challenge.