SMS Verification
- Nick Jensen
Adding SMS-verification to your app can prevent users from creating multiple entity accounts from a single device. At its simplest, adding SMS-verification functionality just adds a single verification step to the basic sign-up process, which starts with endpoint 1001: Create account:Sign-up and verification
{
"firstName": "Alan",
"lastName": "Turing",
"userName": "a_turing",
"password": "3n1gm4",
"mobile": "12345678"
}
{
"dpKey": 12345,
"firstName": "Alan",
"lastName": "Turing",
"userName": "a_turing",
"mobile": "4512345678",
"state": -1
}
The mobile number must of course be a required field for an SMS-verification enabled contract, but it is still a contract field and may be called something else ("mobileNo", "phone" etc.).
readonly "state" field may or may not be included in the contract. The field represents the internal dialogportal entity state where -1 is Unverified, 0 is Active and anything greater than 0 is Inactive.The mobile number must be unique. To ensure this, the mobile number is sanitised and saved with its country-code prefix (45 in this example). If the mobile number is invalid or not unique, a 400 response will be returned - see 1001: Create account for ApiStatusSubCode values.
The unverified entity has been created once the standard 201 response is received. The app should now let the user know that a verification code has been sent via SMS to their mobile number, and should allow the user to input the code. The code format depends on the contract, which will define the number of characters, and whether they are alphabetic, numeric, or a combination. Once the user enters the verification code, the verification is completed using endpoint 2004: Verify account:
{
"code": "0827"
}
Remember that if Data Isolation is enabled, the ApiSessionKey header will need to be read from the 1001: Create account response, and sent as part of the 2004: Verify account request.
When a valid 204 response is received, the entity is verified.
Authentication, before and after verification
As can be seen above, the dpKey is required to verify the entity. If the dpKey is lost before the verification is complete, it can be retrieved using endpoint 2001: Authenticate:
{
"authType": "native",
"loginID": "a_turing",
"password": "3n1gm4"
}
This will return a 403 response, but the important part of the response is the headers:
ApiStatusSubCode: 403.2 DpKey: 12345
Remember that if Data Isolation is enabled, the ApiSessionKey header will also be included in the response, and must be sent as part of the 2004: Verify account request.
The ApiStatusSubCode header value 403.2 means that the entity is unverified, and when this ApiStatusSubCode is received, the DpKey header will also be included.
Once the entity is verified, the authenticate endpoint will return the standard response (with state 0 if that field is included in the contract):
{
"dpKey": 12345,
"firstName": "Alan",
"lastName": "Turing",
"userName": "a_turing",
"mobile": "4512345678",
"state": 0
}
Changing mobile number
Before verification
If an SMS is not received for verification, it may be because the mobile number was entered incorrectly. Use endpoint 1003: Update account data to change the mobile number, and have another verification code SMS sent:
{
"mobile": "12345679"
}
{
"dpKey": 12345,
"firstName": "Alan",
"lastName": "Turing",
"userName": "a_turing",
"mobile": "4512345679",
"state": -1
}
A successful update returns status code 200, and also includes an ApiStatusSubCode:
200.1 | A verification SMS has been sent |
200.2 | The daily verification limit of 5 SMS verifications has been reached for this user. No SMS has been sent! This should be communicated to the user, so they know they need to wait until the next day before trying again. |
200.3 | The minimum time of 2 minutes has not passed since the last verification was sent to this number. No SMS has been sent! This should be communicated to the user, so they know they need to wait before trying again. |
After verification
The default API behaviour is to prevent verified mobile numbers from being changed. In this case, mobile fields sent to endpoint 1003: Update account data will simply be ignored.
However, the contract can be configured to enable updating verified mobile numbers. The new number will need to be verified before the update is complete, so the flow looks like this:
{
"mobile": "12345679"
}
{
"dpKey": 12345,
"firstName": "Alan",
"lastName": "Turing",
"userName": "a_turing",
"mobile": "4512345678",
"state": 0
}
The mobile number has not yet been updated!
The successful update returns status code 200. If a mobile number field was included in the update, and the new number is different to the existing number, and updating verified mobile numbers is enabled for the contract, then an ApiStatusSubCode of 200.1, 200.2 or 200.3 will be included in the response, as described above.
Assuming the entity has not reached the daily SMS verification limit and has therefore received ApiStatusSubCode 200.1, an SMS will have been dispatched to the new number. Once the user receives the SMS containing the verification code, the app should allow them to enter the code and submit the code to endpoint 2004: Verify account, just like completing the verification for the original signup:
{
"code": "0827"
}
A successful 204 response to the verification indicates that the new number has now replaced the old mobile number for the entity.