Widget Guide

Introduction

In this guide we will explain the steps on how to use the Twizo widgets. The Twizo widgets are the easiest way to add 2FA to your website and works on desktops, tablets and mobile devices. If you need help after reading this guide, check out our help section or contact us at support@twizo.com.

We have 2 widgets to make the integration of our service in your website easier:

Verification widget: This widget is used to verify a user during the login process of your website.

Registration widget: This widget is used to register a user for the different verification types.

Try out the Twizo verification widget now by clicking the below button. We will simulate sending a token to you. The valid token you can enter is '012345'.

The verification widget supports all verification types to send the token to you and an option to resend if you did not receive it. Also you can show the user to which number the verification will be sent and you can personalise the widget by setting your own logo.

Verification widget

Integrating the Twizo verification widget is done in 3 simple steps:

Create a verification session.

Open the verification widget.

Verify if the verification session was successful.

Let's explain the steps in more detail.

Step 1: Create a verification session

You start by creating a verification session. When doing that you can set certain parameters like which verification types you want to support, the phone number of the user, token length and type, etc. When the session is created you get a sessionToken. The sessionToken is needed to open the widget.

You will need to use the sessionToken you can find in the response and pass it to the widget, see step 2.

Step 2: Open the widget

Now let's open the widget. You need to include widget.js into your html page and open the widget to show it to the user. Apart from the session token you can do some additional settings like the logo you want to show and the recipient number where the token is sent to.

If malicious people were able to capture the sessionToken, the privacy of the user is still protected. Only if they have the sessionToken and the API key, they are able to collect e.g. the phone number of the user. So always make sure you keep your API key in a safe place.

This is a mandatory parameter. The sessionToken of the verification session you created.

logoUrl

This is an optional parameter. If you want to personalise the widget, you can set a URL to your logo here. We will reduce the size of the logo 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.

recipient

This is an optional parameter. If you set it, the widget will show it to the user to indicate where the token will be sent to. For privacy reasons we recommend not to specify the full number but e.g. only the last 4 digits. So instead of showing '61123456789' show '***6789'.

askTrusted

This is an optional parameter. Possible values are true or false. When it is set to true, the widget will show a checkbox, by default selected, with the text 'Trust this device for x days'. The x will be replaced with the number you fill in for 'trustedDays'. When the widget is closed, the return data contains a property isTrusted indicating if the checkbox was selected or not.

trustedDays

This is a mandatory parameter when askTrusted is set to true. You can specify the number to be shown in the sentence 'Trust this device for x days'.

For security reasons we have set a maximum number of retries for the verification and a maximum time of the session. This to prevent users will perform unlimited unsuccessful verifications. The maximum retries is 5 and the maximum session time is 10 minutes.

When the user completed the verification flow, either by entering the correct token, cancelling, reaching maximum number of retries or reaching the maximum session time, the widget will be closed and you will get the sessionToken, isError (true or false), an errorCode (when isError == true) and returnData returned. The returnData will contain the isTrusted property when askTrusted is set to true.

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

errorCode

Description

When isError is true and the errorCode is empty ('') the user aborted the widget.

101

Verification already verified.

104

Verification failed, please contact your administrator

200

Verification already used

201

Verification timeout

202

Max attempts reached

301

Invalid request

310

Verification failed, unable to start new verification

311

Verification failed, unable to start new verification as the session is already verified or failed

312

Verification failed, unable to start new verification as the session has been expired

313

Verification failed, unable to start new verification as the max attempts has been reached

Step 3: Verify if the verification session was successful

When the widget returned the isError == false the user entered the correct token. However to make sure the verification was indeed successful, you can get the status of the verification session. It is not mandatory to get the status of the session after the widget is closed, but we highly recommend this. Even though we have implemented the widget is a secure way, there are always ways for malicious people to, for example, influence the DOM.

Note: to get the status of a session, you need to specify the sessionToken and the recipient number. You need to specify both as the API will check the combination so that malicious people cannot return a successful sessionToken of a different user.

The status field will show the status, in this case 'success'. When it is success you can continue to login the user, otherwise you can logout the user so he needs to login and do the verification again. For more information on the possible status codes, please check the API documentation.

That's it! These are all the steps you need to do to integrate our verification service into your application to enable 2FA.

Registration widget

Integrating the Twizo registration widget is done in 2 simple steps:

Create a registration session.

Open the registration widget.

Let's explain the steps in more detail.

Step 1: Create a registration session

You start by creating a registration session. When doing that you can set certain parameters like which verification types you want to support, the phone number of the user, etc. When the session is created you get a sessionToken. The sessionToken is needed to open the registration widget.

You will need to use the sessionToken you can find in the response and pass it to the registration widget, see step 2.

Step 2: Open the registration widget

Now let's open the registration widget. You need to include widget.js into your html page and open the widget to show it to the user. Apart from the session token you can do some additional settings like the logo you want to show and the recipient number where the token is sent to.

If malicious people were able to capture the sessionToken, the privacy of the user is still protected. Only if they have the sessionToken and the API key, they are able to collect e.g. the phone number of the user. So always make sure you keep your API key in a safe place.

This is a mandatory parameter. The sessionToken of the registration session you created.

logoUrl

This is an optional parameter. If you want to personalise the widget, you can set a URL to your logo here. We will reduce the size of the logo 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.

recipient

This is an optional parameter. If you set it, the widget will show it to the user to indicate where the token will be sent to. For privacy reasons we recommend not to specify the full number but e.g. only the last 4 digits. So instead of showing '61123456789' show '***6789'.

For security reasons we have set a maximum time of the session. The maximum session time is 15 minutes.

When the widget is closed you will get 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:

errorCode

Description

When isError is true and the errorCode is empty ('') the user aborted the widget.

101

The sessionToken was already used before and cannot be used again to open the registration widget.

102

The session time expired. The maximum session time is 15 minutes.

105

The 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.

201

The account used for the registration session was disabled after the registration widget was opened.

202

The verification service for the account used for the registration session was disabled after the registration widget was opened.

301

The 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 do to integrate our verification service into your application to enable 2FA.

Testing

To test the verification widget you can use a test API key. By setting the recipient number you can define how the verifications will behave. If you set a number ending with '00000' you can enter the token '012345' to have a successful verification. When using a test API key no actual SMS messages or calls will be performed. See Testing for more information on this.

HTTPS requirements

The Twizo widgets are running via secure HTTPS connections. If you want to set your own logo URL, you have to make sure you set a HTTPS connections. If not, the logo will not be shown. We recommend to run your website over HTTPS as well to protect yourself from certain forms of man-in-the-middle attacks.

Browser support

All recent versions of the major browsers on both desktops and mobiles are supported.

If you have an issue with the Twizo widgets on a specific browser, please contact us so we can improve its support.