React native module for Twilio Verify

About

Twilio Verify Push SDK helps you verify users by adding a low-friction, secure, cost-effective, "push verification" factor into your own mobile application. This fully managed API service allows you to seamlessly verify users in-app via a secure channel, without the risks, hassles or costs of One-Time Passcodes (OTPs). This project provides a library to implement Verify Push for your react native app.

Dependencies

• React Native 0.78.x or higher
• React 19.0.x or higher

Installation

• Add the library to your project:

yarn add https://github.com/twilio/twilio-verify-for-react-native.git

• Install the pods for your project

npx pod-install

Enable push notifications

Register your iOS App with APNs

If you want to receive challenges as push notifications, you should register Your App with APNs.

More info here

Add firebase configuration for your Android App

If you want to receive challenges as push notifications, you should add a firebase configuration to your project

• Add a project in Firebase to use cloud messaging for an application ID
• Add the google-services.json file to your project

More info here

Add a push notification library

After setting up push notifications for Android & iOS, you should add a react native library to receive notifications from APN for iOS and FCM for Android.

The example app is using react-native-push-notification, you can find the full example source here

Usage

Twilio Verify availability

You can validate if Twilio Verify is available in the device calling the TwilioVerify.isAvailable method:

await TwilioVerify.isAvailable();

While the Android Keystore is designed to securely manage cryptographic keys (and is used by Twilio Verify), its stability and usability can vary across devices. On some Android devices, the Android Keystore may be unstable or unusable, primarily due to inconsistencies or flaws in the implementation of the Android Keystore system by original equipment manufacturers (OEMs). The SDK implements a retry to obtain a functional instance; therefore, we recommend calling the SDK’s availability method to evaluate whether the device supports the solution.

While the iOS Keychain is designed to securely manage cryptographic keys (and is used by Twilio Verify), its stability and usability can occasionally be affected by device-specific issues, system bugs, or misconfigurations. On a very small percentage of iOS devices, the Keychain may become inaccessible or unreliable, typically due to inconsistencies in device software or rare system-level errors. Therefore, we recommend calling the SDK’s availability method to evaluate whether the device supports the solution.

Keychain Query Mode (iOS only)

You can configure the Keychain query mode to control how the SDK accesses stored factors and keys on iOS. On Android, this setting is a no-op.

Available Modes

• strict: Recommended for new integrations. Filters Keychain items by the specific Service name (TwilioVerify). This isolates the SDK data and prevents collisions with keychain items from other libraries.
• legacy: Queries the Keychain without a Service filter. Warning: May cause collisions if other keychain items exist with similar attributes.

Usage

Call configure() once before any other SDK method:

import TwilioVerify, {
  KeychainQueryMode,
} from '@twilio/twilio-verify-for-react-native';

// For new integrations, use strict mode
await TwilioVerify.configure({ keychainQueryMode: KeychainQueryMode.Strict });

Important Notes

• The default value is Legacy for backward compatibility with existing integrations.
• If you're starting a new integration, it's recommended to use Strict mode to avoid potential Keychain collisions.
• configure() must be called before any other SDK method. Calling it after the SDK has been initialized will result in a rejected promise.

Create factor

import TwilioVerify, {
  PushFactorPayload,
} from '@twilio/twilio-verify-for-react-native';

let factor = await TwilioVerify.createFactor(
  new PushFactorPayload(
    factorName,
    verifyServiceSid,
    identity,
    accessToken,
    pushToken
  )
);

Verify factor

await TwilioVerify.verifyFactor(new VerifyPushFactorPayload(factor.sid));

Get challenge

let challenge = await TwilioVerify.getChallenge(challengeSid, factorSid);

Update challenge

await TwilioVerify.updateChallenge(
  new UpdatePushChallengePayload(factorSid, challengeSid, newStatus)
);

Get factors

let factors = await TwilioVerify.getAllFactors();

Get challenges

let challenges = await TwilioVerify.getAllChallenges(
  new ChallengeListPayload(
    factorSid,
    10,
    ChallengeStatus.Pending,
    ChallengeListOrder.Desc
  )
);

Delete factor

await TwilioVerify.deleteFactor(factorSid);

Clear local storage

You can clear local storage calling the TwilioVerify.clearLocalStorage method:

await TwilioVerify.clearLocalStorage();

Note: Calling this method will not delete factors in Verify Push API, so you need to delete them from your backend to prevent invalid/deleted factors when getting factors for an identity.

Running the Sample app

Install the packages in the twilio-verify-for-react-native project

yarn install

Install the packages in the example app

cd example
yarn install

iOS

• Go to example and install the pods

cd example
npx pod-install

• Change the Bundle Identifier to something unique so Apple’s push notification server can direct pushes to this app

• Enable push notifications

• Get the Access token generation URL from your backend (Running the sample backend). You will use it for creating a factor

• Run iOS app in twilio-verify-for-react-native root folder

yarn example ios

NOTE: There could be incompatibility issues with the react native version and your environment, so running the project from Xcode could share more details about the error and how to fix it

Android

• Follow the steps from Firebase configuration, follow steps 1 to 3

  • For step 3.1, the google-services.json file should be copied to example/android/app
  • Google services plugin is included in the sample app, so you don't need step 3.2

• Get the Access Token generation URL from your backend (Running the Sample backend). You will use it for creating a factor

• Run Android app in twilio-verify-for-react-native root folder

yarn example android

Running the Sample backend

• Configure a Push Credential for the sample app, using the same Firebase project you configured for Android, and using the same APNs configuration for iOS
• Configure a Verify Service, using the Push Credential for the sample app (Android & iOS)
• Go to: https://www.twilio.com/code-exchange/verify-push-backend
• Use the Quick Deploy to Twilio option
  • You should log in to your Twilio account
  • Enter the Verify Service Sid you created above, you can find it here
  • Deploy the application
  • Press Go to live application
  • You will see your backend's start page, copy the url and replace index.html with access-token.(e.g. https://verify-push-backend-xxxxx.twil.io/access-token). This will be your Access Token generation URL

Using the sample app

Adding a factor

• Press Create factor in the factor list
• Enter the identity to use. This value should be an UUID that identifies the user to prevent PII information use
• Enter the Access token URL (Access token generation URL, including the path, e.g. https://verify-push-backend-xxxxx.twil.io/access-token)
• Press Create factor
• Copy the factor Sid

Sending a challenge

• Go to Create a push challenge section in your sample backend (https://verify-push-backend-xxxxx.twil.io/index.html)
• Enter the Identity you used in factor creation
• Enter the Factor Sid you added
• Enter a message. You will see the message in the push notification and in the challenge view
• Enter details to the challenge. You will see them in the challenge view. You can add more details using the Add more Details button
• Press Create challenge button
• You will receive a push notification showing the challenge message in your device.
• The app will show the challenge info below the factor information, in a Challenge section
• Approve or deny the challenge
• After the challenge is updated, you will see the challenge status in the backend's Create a push challenge section, as Login request approved! or Login request denied!, below the Create challenge button

Errors

Types	Code	Description
Initialization	TWILIO_INIT_ERROR	(Android) Exception while initializing Twilio Verify, SDK instance will not be available to use
Initialization	INIT_ERROR	(iOS) Failed to build the TwilioVerify SDK instance, typically due to Keychain access issues. The error message includes details from the native SDK
Configuration	ALREADY_INITIALIZED	configure() was called after the SDK was already initialized. It must be called before any other SDK method
SDK call	TWILIO_VERIFY_ERROR	A Verify SDK call failed, on either platform. The message carries the Verify error code as {60401} …, and the rejection carries a FailureDetail on userInfo — see below

Android

iOS

Diagnosing a failed SDK call

The native SDKs report every failure with a single error code, so the message alone cannot tell you whether Twilio answered and refused the request or was never reached. Rejections from SDK calls therefore carry a FailureDetail on userInfo, where exactly one of two field groups is populated, and which one is the answer:

Group	Fields	Meaning
Twilio answered	httpStatus, apiErrorCode, apiErrorMessage	The request reached Twilio and was refused. apiErrorCode maps to the Verify error reference
Twilio not reached	failureClass, failureMessage, failureChain	The call failed before a response — DNS, TLS, connection, or a local error

try {
  await TwilioVerify.createFactor(payload);
} catch (error) {
  const detail: FailureDetail = error.userInfo ?? {};

  if (detail.httpStatus !== undefined) {
    // Twilio refused it: detail.apiErrorCode says why.
  } else {
    // Twilio was never reached: detail.failureChain names the nested cause,
    // e.g. "SSLHandshakeException < CertificateException".
  }
}

failureChain lists nested failures outermost first, joined by <. The ordering and separator are the same on both platforms; the link format is not, because the platforms identify errors differently — simple class names on Android, domain#code on iOS.

Note the chain links are deliberately shorter than failureClass, which is the fully qualified class name on Android. The chain is meant to be read at a glance as one line, while failureClass identifies the outermost failure precisely.

No request or response body, headers, or credentials are included, and free-text fields are truncated.