Skip to contentSkip to navigationSkip to topbar
Rate this page:
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

import-twilioauth-framework page anchor
Objective-C
Swift

_10
#import <TwilioAuth/TwilioAuth.h>


Setup TwilioAuth instance

setup-twilioauth-instance page anchor
Java
Objective-C
Swift

_10
TwilioAuth twilioAuth = TwilioAuth.getInstance(this);


Register the device with the Authy service

register-the-device-with-the-authy-service page anchor
Java
Objective-C
Swift

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

Make sure the current device is registered by calling isDeviceRegistered.

Check if device is registered

check-if-device-is-registered page anchor
Java
Objective-C
Swift

_10
boolean isDeviceRegistered = twilioAuth.isDeviceRegistered()

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

Java
Objective-C
Swift

_10
String deviceId = twilioAuth.getDeviceId();


To create a new approval request, you can follow the instructions here or use the pre-built Authy API scripts available here(link takes you to an external page).

Call getApprovalRequests to get the list of approval requests:

Java
Objective-C
Swift

_13
long since = ...; // lower limit
_13
long until= ...; // upper limit
_13
TimeInterval timeInterval = new TimeInterval.Builder()
_13
.setSince(since)
_13
.setUntil(until)
_13
.build();
_13
List<ApprovalRequestStatus> statuses = Arrays.asList(
_13
ApprovalRequestStatus.approved,
_13
ApprovalRequestStatus.denied,
_13
ApprovalRequestStatus.expired,
_13
ApprovalRequestStatus.pending);
_13
_13
twilioAuth.getApprovalRequests(statuses, timeInterval);

Call approveRequest or denyRequest to handle approval requests.

Approve or deny a request

approve-or-deny-a-request page anchor
Java
Objective-C
Swift

_10
// Approve
_10
authy.approveRequest(approvalRequest);
_10
_10
// Deny
_10
authy.denyRequest(approvalRequest);

If you configured a callback url in the Dasboard(link takes you to an external page) 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

push-notification-handling page anchor

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

Java
Objective-C
Swift

_10
// pushToken is optional and you include it if you want us to handle push notifications
_10
twilioAuth.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

handle-push-notifications page anchor
Java
Objective-C
Swift

_44
public class MessagingService extends FirebaseMessagingService {
_44
private static final String TAG = MessagingService.class.getSimpleName();
_44
public static final String ONETOUCH_APPROVAL_REQUEST_TYPE = "onetouch_approval_request";
_44
_44
@Override
_44
public void onMessageReceived(RemoteMessage remoteMessage) {
_44
_44
// Check if message contains a data payload.
_44
if (remoteMessage.getData().size() == 0) {
_44
Log.e(TAG, "Received notification with empty payload");
_44
return;
_44
}
_44
_44
if (ONETOUCH_APPROVAL_REQUEST_TYPE.equals(remoteMessage.getData().get("type"))) {
_44
_44
// Since the approval request has sensitive data, we'll fetch it in background with
_44
// the request uuid instead of delivering the information within the userInfo.
_44
_44
// Get the approval request id
_44
String approvalRequestUuid = remoteMessage.getData().get("approval_request_uuid");
_44
_44
TwilioAuth twilioAuth = ((App) getApplicationContext()).getTwilioAuth();
_44
_44
if (!twilioAuth.isDeviceRegistered()) {
_44
throw new RuntimeException("Device should be registered");
_44
}
_44
_44
ApprovalRequest approvalRequest;
_44
_44
try {
_44
ApprovalRequests approvalRequests = twilioAuth.getApprovalRequests(null, null);
_44
_44
approvalRequest = approvalRequests.getApprovalRequestById(approvalRequestUuid);
_44
_44
} catch (TwilioException e) {
_44
throw new RuntimeException(e);
_44
}
_44
_44
if (approvalRequest != null) {
_44
// Do something with the pending approvalRequest
_44
}
_44
}
_44
_44
}


Time-based One Time Passwords (TOTP)

time-based-one-time-passwords-totp page anchor

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 simply 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:

Java
Objective-C
Swift

_10
twilioAuth.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

implement-auttotpdelegatetotpcallback page anchor
Java
Objective-C
Swift

_11
public class TokensFragment extends Fragment implements TOTPCallback {
_11
// ...
_11
_11
void onTOTPReceived(String totp) {
_11
// Display TOTP
_11
}
_11
_11
void onTOTPError(Exception exception) {
_11
// Handle error
_11
}
_11
}

Important note

important-note page anchor

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.


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

Java
Objective-C
Swift

_10
twilioAuth.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.


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

Android issues on github.com(link takes you to an external page)

iOS issues on github.com(link takes you to an external page)


Rate this page: