Skip to main content

​
How to implement

To integrate Prove authentication, you must use the client-side SDK.
  • Using Prove's Possession
  • Using Customer-Supplied Possession
Authentication Overview New Pn
1

Determine Type of Flow

  • Web SDK
  • Android SDK
  • iOS SDK
Determine if the customer is on a mobile or desktop browser using this example. If the isMobile is true, set mobile as the possessionType for the Start() function on the server, otherwise you can set desktop:
// Check if the customer is on a mobile or desktop browser.
const authCheck = new proveAuth.AuthenticatorBuilder().build();
let isMobile = authCheck.isMobileWeb()
2

Initialize the Flow

Send a request to your back end server with the phone number and possession type to start the flow. For additional optional parameters, see the v3/unify API reference.
// Send the Unify request.
rspUnify, err := client.V3.V3UnifyRequest(ctx, &components.V3UnifyRequest{
  PhoneNumber:    "2001004014",
  PossessionType: "mobile",
  ClientRequestId: "test-001",
})
if err != nil {
  t.Fatal(err)
}
The function returns the following fields:
  • authToken: send this to your client-side code to pass into the Authenticate() function - it’s a short lived JSON Web Token (JWT) tied to the current flow and used for the possession checks.
  • correlationId: save this in your current session, then pass it in to the UnifyStatus() function call of the same flow. The correlation ID ties together different system calls for the same Prove flow. It also aids in troubleshooting. The session expires in 15 minutes from when the correlation ID returns from the Unify() call.
  • success: will return pending for this initial call.
Return the authToken in a response to the front end.
3

Authenticate

Once you have the authToken, build the authenticator for both the mobile and desktop flows.
  • Web SDK
  • Android SDK
  • iOS SDK
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))
      .withMobileAuthImplementation("fetch")
      .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);
}

​
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);
  });
}
In the desktop flow, a WebSocket opens for three 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.
If you’re using Content Security Policy headers, ensure you allow wss: device.uat.proveapis.com and wss: device.proveapis.com.
4

Verify Mobile Number

In the AuthFinishStep, you’ll specify a function to call once the possession checks complete on the mobile phone. This endpoint on your back end server calls the UnifyStatus() function to validate the phone number. The AuthFinishStep then completes.
rspUnifyStatus, err := client.V3.V3UnifyStatusRequest(context.TODO(), &components.V3UnifyStatusRequest{
CorrelationID: rspUnify.V3UnifyResponse.CorrelationID,
})
if err != nil {
return fmt.Errorf("error on UnifyStatus(): %w", err)
}
The function returns the following fields:
  • success: either true if the mobile number validation was successful, or false if it failed.
  • phoneNumber: the phone number associated with the possession check.
  • clientHumanId: a client-generated unique ID to identify a specific customer across business lines.
  • clientRequestId: a client-generated unique ID for a specific session. This can be used to identify specific requests.
  • deviceId: the unique identifier for the Prove Key on the device.
  • evaluation: the evaluation result for the Global Fraud Policy.
  • proveId: a unique ID to identify a specific customer obtained from a successful possession check.
You can then respond to the front end with the results of the authentication.

​
Test your Prove implementation

Next, reference the Sandbox test scenarios to test users and simulate different behaviors encountered in production.
Production LaunchTo launch in Production, please contact your Prove representative.
Prove Key BehaviorThe following are things to be aware of when using the Prove Key:
  • Prove Possession - Desktop
  • Prove Possession - Mobile
  • Customer-Supplied Possession
The Prove Key is ignored and Instant Link is performed.

​
Sandbox testing

​
Test users list

Follow the Testing Steps for expected behavior per step.
  • North America
  • International
Phone NumberFirst NameLast Name
2001004014LorantNerger
2001004017JesseMashro

​
Testing steps

Now that you’ve done client-side, server-side, and CX implementation, test using the test users.
  • Lorant
  • Jesse
  • Bertie
  • Wendy
  • Prove Possession - Desktop
  • Prove Possession - Mobile
  • Customer-Supplied Possession
Follow the steps below to test the Prove Unified Authentication flow with Lorant Nerger on desktop. This user will pass the entire Unified Authentication flow using Prove’s possession and return success=true in the /unify-status response.
1

Prompt Customer

Start the onboarding flow on the initial screen and enter the phone number for Lorant Nerger.
2

Initiate Start Request

Your front end will send the phone number, possession type, and final target URL to the back end. Your back end will then send the phone number to the /unify endpoint. The response will provide an auth token, correlation ID, and success=pending because possession still needs to be performed.
3

Send Auth Token to the Front End

Your back end will send the authToken to the front end. The front end will run Instant Link handling.
Example of the Instant Link screen in the Prove Unified Authentication sandbox testing flow
4

Verify Mobile Number

Once the front end finishes the possession check, the back end calls the /unify-status endpoint with the correlation ID to validate the phone number. The response provides:
  • proveId that is tied to this user.
  • success=true
  • phoneNumber that was initially passed.
You have a successful flow but no device ID is placed as it only applies to mobile devices. Send the user on through your authenticated flow.