On this page

Quick Reference

(warning)

Warning

The TwilioAuth SDK has been deprecated. This means that while we will continue to provide maintenance support for existing customers and their usage, we discourage new customers and new usage, as we may shut it down entirely in the future. We strongly recommend using the Verify Push SDK instead, which currently supports the Push channel, and will be enhanced to support the TOTP channel in the future.

For iOS projects, make sure you import the framework in the files in which you will interact with the SDK.

Import TwilioAuth framework

1#import <TwilioAuth/TwilioAuth.h>

Setup TwilioAuth instance

1TwilioAuth twilioAuth = TwilioAuth.getInstance(this);

Register the device with the Authy service

1// You should obtain the registration token from your backend 
2// pushToken is optional and you include it if you want us to handle push notifications  
3twilioAuth.registerDevice(registrationToken, pushToken);

Make sure the current device is registered by calling isDeviceRegistered.

Check if device is registered

1boolean isDeviceRegistered = twilioAuth.isDeviceRegistered()

To obtain the device id, call the getDeviceId method. This method will be useful for device specific operations such as deletion.

Get Device ID

1String deviceId = twilioAuth.getDeviceId();

Approval Requests

To create a new approval request, you can follow the instructions here or use the pre-built Authy API scripts available here.

Call getApprovalRequests to get the list of approval requests:

Get approval requests

1long since = ...; // lower limit
2long until= ...; // upper limit
3TimeInterval timeInterval = new TimeInterval.Builder()
4                                         .setSince(since)
5                                         .setUntil(until)
6                                         .build();
7List<ApprovalRequestStatus> statuses = Arrays.asList(
8                                              ApprovalRequestStatus.approved, 
9                                              ApprovalRequestStatus.denied, 
10                                              ApprovalRequestStatus.expired, 
11                                              ApprovalRequestStatus.pending);
12
13twilioAuth.getApprovalRequests(statuses, timeInterval);

Call approveRequest or denyRequest to handle approval requests.

Approve or deny a request

1// Approve
2authy.approveRequest(approvalRequest);
3
4// Deny
5authy.denyRequest(approvalRequest);

If you configured a callback URL in the Dashboard to receive notifications when a user approves/denies a request it will be called after this step. Otherwise you should poll the OneTouch API. For more details go here.

Push notification handling

In order to interact with the request notifications you will need to update the push token every time it changes in the device.

1// pushToken is optional and you include it if you want us to handle push notifications  
2twilioAuth.setPushToken(pushToken);

Once the notification arrives, you will need to pull it from the TwilioAuth API. The reason for this is that it contains sensitive information, so the device must retrieve it through the TwilioAuth SDK instead of having it directly in the notification payload.

Handle push notifications

1public class MessagingService extends FirebaseMessagingService {
2    private static final String TAG = MessagingService.class.getSimpleName();
3    public static final String ONETOUCH_APPROVAL_REQUEST_TYPE = "onetouch_approval_request";
4
5    @Override
6    public void onMessageReceived(RemoteMessage remoteMessage) {
7
8        // Check if message contains a data payload.
9        if (remoteMessage.getData().size() == 0) {
10            Log.e(TAG, "Received notification with empty payload");
11            return;
12        }
13
14        if (ONETOUCH_APPROVAL_REQUEST_TYPE.equals(remoteMessage.getData().get("type"))) {
15            
16            // Since the approval request has sensitive data, we'll fetch it in background with
17            // the request uuid instead of delivering the information within the userInfo.
18
19            // Get the approval request id
20            String approvalRequestUuid = remoteMessage.getData().get("approval_request_uuid");
21
22            TwilioAuth twilioAuth = ((App) getApplicationContext()).getTwilioAuth();
23
24            if (!twilioAuth.isDeviceRegistered()) {
25                throw new RuntimeException("Device should be registered");
26            }
27
28            ApprovalRequest approvalRequest;
29
30            try {
31                ApprovalRequests approvalRequests = twilioAuth.getApprovalRequests(null, null);
32
33                approvalRequest = approvalRequests.getApprovalRequestById(approvalRequestUuid);
34
35            } catch (TwilioException e) {
36                throw new RuntimeException(e);
37            }
38
39            if (approvalRequest != null) {
40                // Do something with the pending approvalRequest
41            }
42        }
43
44    }

Time-based One Time Passwords (TOTP)

As a fallback when OneTouch requests aren't functioning (more specifically, if the user is in Airplane mode, has no Wi-Fi/cell connection, misses the push notification, or prefers to type the generated code in for validation instead of pushing the Approve/Deny button) you can obtain a TOTP.

The TOTP will be valid for 30 seconds and you can obtain it as follows:

Get TOTP

1twilioAuth.getTOTP(this);

Additionally your class must implement the AUTTOTPDelegate protocol (on iOS) or the TOTPCallback interface (on Android) to be able to receive the TOTP:

Implement AUTTOTPDelegate/TOTPCallback

1public class TokensFragment extends Fragment implements TOTPCallback {
2	// ...
3
4	void onTOTPReceived(String totp) {
5		// Display TOTP
6	}
7
8	void onTOTPError(Exception exception) {
9		// Handle error
10	}
11}

Important note

This delegate/callback listener will receive a TOTP immediately, which will be generated with the local token. Then the SDK will try to sync the token with TwilioAuth API in the background. If that token differs (i.e. digits changed, seed was rotated, or token was removed) your delegate will receive another call with the newest TOTP.

Helper methods

To delete the device local data you can use the following method:

Clear Local Data

1twilioAuth.clearLocalData();

Please note this method doesn't delete the device in the Authy backend, it only clears the data stored locally on the device. For example, you may use this method as a logout option inside your app.

Support

If you find any inconveniences while following this guide please file us an issue

Android issues on github.com

iOS issues on github.com