How to integrate the Twizo Registration widget

The Twizo Registration widget eliminates the requirement for functionality implementation to enable 2FA (i.e. generating a QR or back-up code). Next to that, integration of the widget is plain and simple. It only requires 2 steps: 

  1. Create a registration session. Registration session is a temporary session for the user so the registration widget knows which user is managing his 2FA settings.
  2. Open the registration widget. The registration widget will be shown to the user where he can manage his 2FA settings.

Let’s explain the steps in more detail below.

Twizo Logo

Step 1: Create a registration session

First, start by creating a registration session. After doing so, you are able to set certain parameters, such as the verification type you would like to support. After the session has been created you will receive a session token. The sessionToken is required in order to open the registration widget.

Here’s an example of how to create a registration session:

curl -X POST https://api-<?php echo $region; ?>-01.twizo.com/v1/widget-register-verification/session \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "twizo:<API_KEY>" \
-d '{
    "recipient" : "601234500000"
    "backupCodeIdentifier" : "me@twizo.com"
    "totpIdentifier" : "me@twizo.com"
    "issuer" : "Twizo"
}'
$widgetSession = $twizo->createWidgetRegisterSession(array('sms','call'));
$widgetSession->setRecipient('601234500000');
$widgetSession->create();

You will get a response similar to this to this one:

{
    "sessionToken": "<?php echo $region; ?>-01_1161130_wid5aab9dec9bca47.995159356758",
    "applicationTag": "Default application",
    "requestedTypes": [
        "sms",
        "call",
        "totp",
        "push",
        "backupcode",
        "biovoice",
        "telegram",
        "line",
    ],
    "registeredTypes": [
        "sms",
        "call",
        "telegram"
    ],
    "allowedTypes": [
        "sms",
        "call",
        "totp",
        "push",
        "backupcode",
        "biovoice",
        "telegram",
        "line"
    ],
    "recipient": "601234500000",
    "totpIdentifier": "me@twizo.com",
    "backupCodeIdentifier": "me@twizo.com",
    "issuer": "Twizo",
    "language": "en",
    "status": "no status",
    "statusCode": 0,
    "createdDateTime": "2018-03-16T10:35:24+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/<?php echo $region; ?>-01.twizo.com\/v1\/widget-register-verification\/session\/<?php echo $region; ?>-01_1161130_wid5aab9dec9bca47.995159356758"
        }
    }
}

Check our API documentation to see all options you can set once creating a registration session.

Once you have obtained the sessionToken, retrieved from the response, you can open the registration as described in the step 2.

Step 2: Open the registration widget

Now, let’s open the registration widget. You will need to include “widget.js” into your html page and open the widget to show it to the user. Apart from the sessionToken, you can adjust some additional settings, such as the logo you wish to display and the recipient number the token is sent to.

Note that if malicious criminals were able to capture the sessionToken, the privacy of the user is still protected. Only if both the sessionToken and the API key are obtained, they are able to collect vulnerable data of the user. Accordingly, always make sure you keep your API key in a safe place.

The URL of the widget.js is:

https://cdn.twizo.com/widget.js

Javascript code to open the widget:

var handler = TwizoRegisterWidget.configure({
  sessionToken: sessionToken,
});

handler.open(function (sessionToken, isError, errorCode, registeredTypes) {
  if (isError) {
    return console.log('Got an error: ' + errorCode);
  }

  // Success...
});

The options you can set for the registration widget are:

ParameterDescription
sessionTokenThis is a mandatory parameter. The sessionToken of the registration session you created.
logoUrlThis is an optional parameter. If you want to personalize the widget, you can set a URL to your logo here. The size of the logo will be reduced to 200 pixels wide and 90 pixels high.

Please note, as the widget is using HTTPS, the link to the logo must be HTTPS as well. See HTTPS for more information.

recipientThis is an optional parameter. Once this parameter is set, the widget will show it to the user to indicate where the token will be sent to. For privacy purposes, we recommend not to specify the full number but only the last 4 digits. So instead of showing ‘61123456789’ show ‘***6789’.

For security reasons, we have set a maximum session time to 15 minutes.

Once the widget is closed you will receive the sessionToken, isError (true or false), an errorCode (when isError == true) and registeredTypes returned. The registeredTypes will contain an array with the verification types the user has now registered for.

The errorCodes property can be one of the following error codes:

errorCodeDescription
 When isError is true and the errorCode is empty (”) the user aborted the widget.
101The sessionToken was already used before and cannot be used again to open the registration widget.
102The session time expired. The maximum session time is 15 minutes.
105The user is trying to register for a verification type which is not allowed. This can happen when the registration widget is open and you disable a verification type for your users.
201The account used for the registration session was disabled after the registration widget was opened.
202The verification service for the account used for the registration session was disabled after the registration widget was opened.
301The bio voice registration failed. There can be numerous reasons why it failed, e.g. the country of the user is not supported for bio voice. Please contact support for more information.

That’s it! These are all the steps you need to take in order to integrate our verification service into your application to enable 2FA.