Skip to main content

​
Supported languages

Prove provides client web SDKs in the following languages: TypeScript and JavaScript.

​
Installation

The Prove Platform Web SDK has an unpacked size of 171 KB, and a single dependency: @prove-identity/mobile-auth. Install the client-side SDK of your choice by running a command in your terminal, or by using a dependency management tool specific to your project. 
# Run this command to install the package (ensure you have the latest version).
npm install @prove-identity/prove-auth@3.1.1
Angular TypeScript Compilation ErrorSome Angular projects may experience TypeScript compilation errors when building with the Prove Web SDK. This is a known issue that affects various Angular versions.To correct this, add or update the skipLibCheck setting in your tsconfig.json file:
tsconfig.json
{
  "compilerOptions": {
    "skipLibCheck": true,
    // ... other options
  }
}
This setting tells TypeScript to skip type checking of declaration files (.d.ts files) from external libraries, which resolves the compilation issues while maintaining type safety for your own code.Affected Versions:
  • Angular 17.x (confirmed with Angular 17.3.3)
  • Other Angular versions may also be affected

​
Find the type of flow: mobile or desktop

You can find if the customer is on a mobile or desktop browser using this example. If the isMobile is true, pass mobile to the Start() function on the server, otherwise you can pass desktop: 
// Check if the customer is on a mobile or desktop browser.
const authCheck = new proveAuth.AuthenticatorBuilder().build();
let isMobile = authCheck.isMobileWeb()
In a mobile flow, Mobile Auth executes first and if that fails, performs one-time password (OTP) validation on the mobile phone. In a desktop flow, Instant Link sends a text message to the mobile phone for verification. In the mobile flow, once either Mobile Auth or the OTP validation completes, the AuthFinishStep function finishes.
Mobile AuthIn order for Mobile Auth to succeed:
  • Disable VPN.
  • Disable Private Relay on iOS.
When testing, you can ignore any Chrome error messages that mention ERR_TUNNEL_CONNECTION_FAILED - this is due to the VPN, but the SDK fallbacks to OTP.
In the desktop flow, a WebSocket opens for 3 minutes on the desktop browser while waiting for the customer to select the link in the text message. Once clicked, the WebSocket closes and the AuthFinishStep function finishes.

​
Authenticate()

The SDK requires an authToken as a parameter for the Authenticate() function. This token returns from the Start() call of the server-side SDK. The token is session specific, limiting it to a single flow. It also expires after 15 minutes.

​
Retrieve authToken

Send a request to your back end server with the phone number, flow type, and an optional challenge to start the flow. This can either be the date of birth or last four digits of the social security number. 
async function initialize(phoneNumber, ssn, flowType) {
  const response = await fetch(backendUrl + "/initialize", {
    method: "POST",
    headers: {
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phoneNumber: phoneNumber,
      flowType: flowType,
      ssn: ssn,
    }),
  });

  const rsp = await response.json();
  const authToken = rsp.authToken;

  return authToken;
}

​
Setup authenticator

Once you have the authToken, build the authenticator for both the mobile and desktop flows.
Mobile Auth Implementations OnlyIf your application uses Content Security Policy headers, you must configure them to allow WebSocket connections to Prove’s authentication services:Sandbox Environment
  • https://device.uat.proveapis.com:4443
  • https://device.uat.proveapis.com
  • http://device.uat.proveapis.com:4443
  • http://device.uat.proveapis.com
Production Environment
  • https://device.proveapis.com:4443
  • https://device.proveapis.com
  • http://device.proveapis.com:4443
  • http://device.proveapis.com
  • https://auth.svcs.verizon.com:22790
Failure to configure these properly will prevent Mobile Auth functionality from working correctly in web flows.
async function authenticate(isMobileWeb, authToken) {
  // Set up the authenticator for either mobile or desktop flow.
  let builder = new proveAuth.AuthenticatorBuilder();

  if (isMobileWeb) {
    // Set up Mobile Auth and OTP.
    builder = builder
      .withAuthFinishStep((input) => verify(input.authId))
      .withOtpFallback(otpStart, otpFinish);
  } else {
    // Set up Instant Link.
    builder = builder
      .withAuthFinishStep((input) => verify(input.authId))
      .withInstantLinkFallback(instantLink)
      .withRole("secondary");
  }

  const authenticator = builder.build();

  // Authenticate with the authToken.
  return authenticator.authenticate(authToken);
}

​
Validate the mobile phone

In the AuthFinishStep, specify a function to call once the possession checks complete on the mobile phone. This endpoint on your back end server calls the Validate() function to validate the phone number. If it was successful, the server returns the results from the Challenge() function including customer information. Refer to the following example fields that return and then prefill on a form for the customer to verify. The AuthFinishStep then completes. If a user cancels, the server makes a call to the Validate() function and returns success=false. 
// Send a verify request to get return customer information.
async function verify() {
  const response = await fetch(backendUrl + "/verify", {
    method: "POST",
    headers: {
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}),
  });

  const results = await response.json();
  const rsp = JSON.stringify(results);

  const firstName = document.getElementById("firstNameInput");
  const lastName = document.getElementById("lastNameInput");

  firstName.value = rsp.firstName;
  lastName.value = rsp.lastName;

  return null;
}

​
Configure OTP

To use the Resend/Retry/Phone Change features, you need to install the Web SDK version 2.15.1 or later.
To set the One-Time Password (OTP) handler, withOtpFallback(startStep: OtpStartStep | OtpStartStepFn, finishStep: OtpFinishStep | OtpFinishStepFn), requires implementing the OtpStartStep and OtpFinishStep. When returning the phone number in the functions, ensure you return an object with the field phoneNumber to the resolve() function. The OTP session has a two minute timeout from when it’s sent through Short Message Service (SMS) to when the customer can enter in the OTP.
  • Default
  • Prompt for Phone Number
  • Resend
  • Retry OTP
  • Phone Number Change
Follow these instructions if you are implementing OTP and you are passing in the phone number on the /v3/start endpoint. In this case, you’ve already prompted for a phone number so you don’t need to prompt for it in the client SDK.Since you passed the phone number in the Start() function, call resolve(null) to communicate to the SDK you have the customer’s agreement to deliver the SMS message. Ensure you return an object to resolve() function.
function otpStartStep(phoneNumberNeeded, phoneValidationError) {
  return new Promise((resolve, reject) => {
    // Since no phone number is needed, don't prompt the user.
    resolve(null);
  });
}
Call the reject('some error message') method to communicate to the SDK any issues while trying to obtain the phone number or the OTP. Report an error if the customer cancels the SMS transaction or presses the back button to leave the screen.In the finish step, call the resolve(result: OtpFinishResult) method to return the collected OTP value in which result variable has OnSuccess value for OtpFinishResultType and the OTP value wrapped in OtpFinishInput.
function otpFinishStep(otpError) {
  return new Promise((resolve, reject) => {
    // If error message is found, handle it.
    if (otpError) {
      // Set to a variable and display it in a field.
      // In this example, we don't do anything with the error.
      var someErrorMessage = otpError.message;
    }

    // Prompt the user for whether they received the SMS.
    // Typically, this is a page that shows the OTP already. We are simplifying
    // it by requiring an input.
    var input = confirm('Did you receive a text message?');
    if (!input) {
      // Close the modal if a text message was not received.
      return;
    }

    // Prompt the user for the OTP.
    var otp = prompt('Enter OTP code:');
    if (otp) {
      // If the input is valid and the user clicked `OK`, return the OTP.
      resolve({
        input: { otp }, // OTP value
        resultType: 0, // OnSuccess enum type = 0
      });
    } else {
      // Else, exit the flow.
      reject('phone invalid or user cancelled');
    }
  });
}
To use the Resend/Retry/Phone Change features, you need to install the Web SDK version 2.15.1 or later.
To set the Instant Link handler, withInstantLinkFallback(startStep: InstantLinkStartStep | InstantLinkStartStepFn, retryStep?: InstantLinkRetryStep | InstantLinkRetryStepFn) requires implementing the InstantLinkStartStep interface and optionally the InstantLinkRetryStep interface if you wish for advanced capabilities. When returning the phone number in the functions, ensure you return an object with the field phoneNumber to the resolve() function. The Instant Link session has a three minute timeout from when it’s sent through Short Message Service (SMS) to when the customer can click the received link.
  • Default
  • Prompt for Phone Number
  • Resend
  • Phone Number Change
Follow these instructions if you are implementing Instant Link and you are passing in the phone number on the /v3/start endpoint. In this case, you’ve already prompted for a phone number so you don’t need to prompt for it in the client SDK.Since you passed the phone number in the Start() function, call resolve(null) to communicate to the SDK you have the customer’s agreement to deliver the SMS message. Ensure you return an object to resolve() function.
function instantLinkStartStep(phoneNumberNeeded, phoneValidationError) {
  return new Promise((resolve, reject) => {
    // Since no phone number is needed, don't prompt the user.
    resolve(null);
  });
}

​
Verify the Customer Information

Once the customer has made any edits to their prefill information, submit that information to the back end server so the Complete() call can then verify the customer information. 
// Send request to the backend to verify customer information.
async function sendInfo(firstName, lastName) {
  const response = await fetch(backendUrl + "/finish", {
    method: "POST",
    headers: {
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      firstName: firstName,
      lastName: lastName,
    }),
  });
  const results = await response.json();
  const rsp = JSON.stringify(results);

  return rsp;
}

​
Function reference

Start the flow with Authenticator.authenticate(), while creating an instance of Authenticator using AuthenticatorBuilder.build(). Use the following methods to configure Authenticator before instantiating. All methods return the same instance of AuthenticatorBuilder to allow chaining of the configuration methods. withAuthFinishStep(step: AuthFinishStep | AuthFinishStepFn): AuthenticatorBuilder This step customizes the handling of the authentication finish call. The implementation calls the customer’s back end to retrieve authentication results. The customer defines the format of the response to suit the needs of the app. withRole(role: DeviceRole): AuthenticatorBuilder Sets the authentication role for this device. It can be either Primary or Secondary. The Primary value sets when the customer is on a mobile device web browser that registers with the Prove system and later authenticated by verifying this registration. On other hand, the Secondary value sets when the customer is on a desktop web browser, which authenticates after receiving customer feedback on their Primary device. withMobileAuthImplementation(implementation: MobileAuthImplementation): AuthenticatorBuilder Sets the implementation type for Mobile Auth authenticator. Possible values are Fetch or Pixel with Fetch set by default. withDeviceIpAddress(deviceIp: string | (() => string | null) | null): AuthenticatorBuilder Sets the public IP address for this device to report during device registration. If you neglect to call this method, or the IP address value is null, the system attempts to autodetect the IP address using an external service. If the service is inaccessible, the system uses the client’s IP address of the HTTP connection. Successful Mobile Auth authentication requires the client’s public IP address. withOtpFallback(startStep: OtpStartStep | OtpStartStepFn, finishStep: OtpFinishStep | OtpFinishStepFn): AuthenticatorBuilder Configure start and finish handlers for SMS OTP authenticator. Collecting customer input requires using these handlers to enter the phone number for delivery of OTP codes, and to enter received OTP codes. withInstantLinkFallback(instantLinkStartStep: InstantLinkStartStep | InstantLinkStartStepFn, instantLinkRetryStep?: InstantLinkRetryStep | InstantLinkRetryStepFn): AuthenticatorBuilder Configure handler for Instant Link authenticator. This handler collects customer input to enter the phone number for Instant Link. build(): Authenticator Finalizes the configuration and returns an instance of the Authenticator.