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
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 flowType 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

  • No Mobile Auth
  • Mobile Auth
Send a request to your back end server with the phone number and possession type to start the flow.Additional parameters:
  • finalTargetURL: required when flowType=desktop. This should be a URL you maintain. Once the customer clicks the Instant Link, they will be redirected to this URL. It should instruct the customer to continue the workflow. Maximum length is 128 characters.
  • checkReputation: if true, TrustScore verification will be performed.
  • 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.
  • smsMessage: optional field to customize the message body sent in the Instant Link or OTP SMS message. Otherwise, you can use Prove defaults.
  • clientCustomerId: a client-generated unique ID for a specific customer. You can link calls related to the same customer, across different requests or sessions. The client defines the format of this ID.
  • deviceId: the unique identifier for the Prove Key on the device.
  • emailAddress: the email address of the customer.
  • ipAddress: the IP address of the customer.
  • proveId: a unique ID to identify a specific customer obtained from a previous successful authentication.
    For OTP retries, make sure to implement client SDK changes in the next step.
// Send the Unify request.
rspUnify, err := client.V3.V3UnifyRequest(ctx, &components.V3UnifyRequest{
  PhoneNumber:    "2001004014",
  PossessionType: "mobile",
  ClientRequestID: provesdkservergo.String("client-abc-123"),
  AllowOTPRetry: true,
})
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);
}
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: if provided in the request.
  • clientRequestId: if provided in the request.
  • 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.
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.