Implementation Guide

Prerequisites

Sandbox credentials: Ensure you have Prove Sandbox credentials from the Developer Portal. To access Sandbox credentials, follow the steps outlined on the Authentication page. To access the Prove API, you’ll need to use your OAuth client ID and client secret. You can load these from environment variables or another method:

// Get environment variables.
clientID := os.Getenv("PROVE_CLIENT_ID")
if len(clientID) == 0 {
  return fmt.Errorf("missing env variable: %s", "PROVE_CLIENT_ID")
}

clientSecret := os.Getenv("PROVE_CLIENT_SECRET")
if len(clientSecret) == 0 {
  return fmt.Errorf("missing env variable: %s", "PROVE_CLIENT_SECRET")
}

proveEnv := "uat-us" // Use UAT in US region.

// Create client for Prove API.
client := provesdkservergo.New(
  provesdkservergo.WithServer(proveEnv),
  provesdkservergo.WithSecurity(components.Security{
    ClientID:     provesdkservergo.String(clientID),
    ClientSecret: provesdkservergo.String(clientSecret),
  }),
)

Token Expiration

The OAuth token expires after 60 minutes, requiring you to get another token.

Server-side SDK: Install the server-side SDK of your choice by running a command in your terminal, or by using a dependency management tool specific to your project.

# The Go library is hosted on GitHub so you can use this command to import it
# to your Go application.
go get github.com/prove-identity/prove-sdk-server-go

# Ensure you import the SDK in your code like this:
import (
	provesdkservergo "github.com/prove-identity/prove-sdk-server-go"
	"github.com/prove-identity/prove-sdk-server-go/models/components"
)

Client-side SDK: 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.

To integrate solutions, you must use the client-side SDK.

# Run this command to install the package (ensure you have the latest version).
npm install @prove-identity/prove-auth@2.8.2

# Run this command to install the package (ensure you have the latest version).
npm install @prove-identity/prove-auth@2.8.2

Prove manages a maven repository with Android binaries to enable integration with Gradle.

Update the dependencies object in the build.gradle file:

Java

dependencies {
  // Existing dependencies are here.

  // Add the Prove Link dependencies:
  implementation 'com.prove.sdk:proveauth:6.3.0'
}

You’ll also need to point to the repository by updating your settings.gradle file with the Maven repository:

Java

dependencyResolutionManagement {
    // Existing repository settings are here.

    repositories {
        // Existing repositories are here.

        // Add the Prove Link Maven repository:
        maven {
            url = "https://prove.jfrog.io/artifactory/libs-public-maven/"
        }
    }
}

The following needs added to the build.gradle file to also download dependency libraries:

Java

dependencies {
  implementation fileTree('libs')
}

If you receive an error message on the application@fullBackupContent value, you can resolve it by adding this line of code to your application AndroidManifest.xml file inside the <application>...</application> node. Add it as an attribute to the opening application tag:

XML

<application
...
tools:replace="android:fullBackupContent"
...>
</application>

The Prove Auth SDK and its children SDKs merge the following permissions into the main application:

XML

<!-- Required to perform authentication -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Required to access information about networks -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Required for ConnectivityManager.requestNetwork -->
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />

Prove manages a repository with the libraries to enable integration.

Execute the following to import CocoaPod from the Prove pod repository:

shell

# Run this command to install the cocoapods-art plugin (authored by Artifactory)
gem install cocoapods-art

# Run this command to add the Prove pod repository
pod repo-art add prove.jfrog.io https://prove.jfrog.io/artifactory/api/pods/libs-public-cocoapods

# In your Podfile, paste in the Prove pod repository as a source
plugin 'cocoapods-art', :sources => [
    'prove.jfrog.io'
]

# In your Podfile, paste in the SDK pods
pod 'ProveAuth', '6.3.1'

# Run this command to install the SDK pods
pod install

Implement Prove Pre-Fill

Prompt Customer

Create or update your first screen to prompt for phone number and challenge data.

Determine Type of Flow

You can 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()

// Check if the customer is on a mobile or desktop browser.
const authCheck = new proveAuth.AuthenticatorBuilder().build();
let isMobile = authCheck.isMobileWeb()

When using the Android SDK, set mobile as the flowType for the Start() function on the server.

When using the iOS SDK, set mobile as the flowType for the Start() function on the server.

Initialize the Flow

You need to 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;
}

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;
}

Java

  String initialize(String phoneNumber, String ssn, String flowType) {
      YourBackendClient backend = new YourBackendClient(); // Backend API client

      // TODO: Build your InitializeRequest object
      InitializeRequest initializeRequest = new InitializeRequest(phoneNumber, ssn, flowType);

      // Send an initialize request to your backend server to get authToken
      InitializeResponse response = backend.initialize(initializeRequest);

      // TODO: define your own InitializeResponse object to parse authToken string
      return response.getAuthToken();
  }

Swift

  // The below example uses native iOS URLSession, but any other
  // alternative networking approaches should also work
  func initialize(phoneNumber: String, ssn: String, flowType: String, completion: @escaping (Result\<String, Error>) -> Void) {
      guard let url = URL(string: "\(backendUrl)/initialize") else {
          completion(.failure(URLError(.badURL)))
          return
      }
      var request = URLRequest(url: url)
      request.httpMethod = "POST"
      request.addValue("application/json", forHTTPHeaderField: "Accept")
      request.addValue("application/json", forHTTPHeaderField: "Content-Type")
      // Set up the request body
      let body: [String: Any] = [
          "phoneNumber": phoneNumber,
          "flowType": flowType,
          "ssn": ssn
      ]
      do {
          request.httpBody = try JSONSerialization.data(withJSONObject: body, options: \[])
      } catch {
          completion(.failure(error))
          return
      }
      // Perform the request
      let task = URLSession.shared.dataTask(with: request) { \_, response, error in
          // Handle network or connection errors
          if let error = error {
              completion(.failure(error))
              return
          }
          do {
              if let json = try JSONSerialization.jsonObject(with: data, options: \[]) as? [String: Any],
                 let authToken = json["authToken"] as? String {
                  completion(.success(authToken))
              } else {
                  let parsingError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey : "Failed to parse JSON or authToken is missing"])
                  completion(.failure(parsingError))
              }
          } catch {
              completion(.failure(error))
          }
      }
      // Start the network call
      task.resume()
  }

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;
}

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;
}

Java

  String initialize(String phoneNumber, String ssn, String flowType) {
      YourBackendClient backend = new YourBackendClient(); // Backend API client

      // TODO: Build your InitializeRequest object
      InitializeRequest initializeRequest = new InitializeRequest(phoneNumber, ssn, flowType);

      // Send an initialize request to your backend server to get authToken
      InitializeResponse response = backend.initialize(initializeRequest);

      // TODO: define your own InitializeResponse object to parse authToken string
      return response.getAuthToken();
  }

Swift

  // The below example uses native iOS URLSession, but any other
  // alternative networking approaches should also work
  func initialize(phoneNumber: String, ssn: String, flowType: String, completion: @escaping (Result\<String, Error>) -> Void) {
      guard let url = URL(string: "\(backendUrl)/initialize") else {
          completion(.failure(URLError(.badURL)))
          return
      }
      var request = URLRequest(url: url)
      request.httpMethod = "POST"
      request.addValue("application/json", forHTTPHeaderField: "Accept")
      request.addValue("application/json", forHTTPHeaderField: "Content-Type")
      // Set up the request body
      let body: [String: Any] = [
          "phoneNumber": phoneNumber,
          "flowType": flowType,
          "ssn": ssn
      ]
      do {
          request.httpBody = try JSONSerialization.data(withJSONObject: body, options: \[])
      } catch {
          completion(.failure(error))
          return
      }
      // Perform the request
      let task = URLSession.shared.dataTask(with: request) { \_, response, error in
          // Handle network or connection errors
          if let error = error {
              completion(.failure(error))
              return
          }
          do {
              if let json = try JSONSerialization.jsonObject(with: data, options: \[]) as? [String: Any],
                 let authToken = json["authToken"] as? String {
                  completion(.success(authToken))
              } else {
                  let parsingError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey : "Failed to parse JSON or authToken is missing"])
                  completion(.failure(parsingError))
              }
          } catch {
              completion(.failure(error))
          }
      }
      // Start the network call
      task.resume()
  }

You need to send a request to your back end server with the flow type.

async function initialize(flowType) {
  const response = await fetch(backendUrl + "/initialize", {
    method: "POST",
    headers: {
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      flowType: flowType,
    }),
  });

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

  return authToken;
}

async function initialize(flowType) {
  const response = await fetch(backendUrl + "/initialize", {
    method: "POST",
    headers: {
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      flowType: flowType,
    }),
  });

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

  return authToken;
}

Java

  String initialize(String flowType) {
      YourBackendClient backend = new YourBackendClient(); // Backend API client

      // TODO: Build your InitializeRequest object
      InitializeRequest initializeRequest = new InitializeRequest(flowType);

      // Send an initialize request to your backend server to get authToken
      InitializeResponse response = backend.initialize(initializeRequest);

      // TODO: define your own InitializeResponse object to parse authToken string
      return response.getAuthToken();
  }

Swift

  // The below example uses native iOS URLSession, but any other
  // alternative networking approaches should also work
  func initialize(flowType: String, completion: @escaping (Result\<String, Error>) -> Void) {
      guard let url = URL(string: "\(backendUrl)/initialize") else {
          completion(.failure(URLError(.badURL)))
          return
      }
      var request = URLRequest(url: url)
      request.httpMethod = "POST"
      request.addValue("application/json", forHTTPHeaderField: "Accept")
      request.addValue("application/json", forHTTPHeaderField: "Content-Type")
      // Set up the request body
      let body: [String: Any] = [
          "flowType": flowType
      ]
      do {
          request.httpBody = try JSONSerialization.data(withJSONObject: body, options: \[])
      } catch {
          completion(.failure(error))
          return
      }
      // Perform the request
      let task = URLSession.shared.dataTask(with: request) { \_, response, error in
          // Handle network or connection errors
          if let error = error {
              completion(.failure(error))
              return
          }
          do {
              if let json = try JSONSerialization.jsonObject(with: data, options: \[]) as? [String: Any],
                 let authToken = json["authToken"] as? String {
                  completion(.success(authToken))
              } else {
                  let parsingError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey : "Failed to parse JSON or authToken is missing"])
                  completion(.failure(parsingError))
              }
          } catch {
              completion(.failure(error))
          }
      }
      // Start the network call
      task.resume()
  }

Call the Start Endpoint

On the back end, you’ll start a Prove flow with a call to the Start() function. This function takes these required parameters:

flowType: either desktop or mobile to describe which type of device the customer is starting their flow on.
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.

These parameters are optional:

ssn: full or last four digits of the customer’s social security number. You can pass it into Start() or Challenge().
dob: date of birth in one of these formats: YYYY-MM-DD, YYYY-MM, MM-DD. You can pass it into Start() or Challenge().

// Send the start request.
rspStart, err := client.V3.V3StartRequest(context.TODO(), &components.V3StartRequest{
  PhoneNumber: "2001001693"
  FlowType:       "desktop",
  FinalTargetURL: provesdkservergo.String("https://www.example.com"),
  Ssn: "470806227",
})
if err != nil {
  return fmt.Errorf("error on Start: %w", err)
}

// Send the start request.
rspStart, err := client.V3.V3StartRequest(context.TODO(), &components.V3StartRequest{
  PhoneNumber: "2001001693"
  FlowType:       "desktop",
  FinalTargetURL: provesdkservergo.String("https://www.example.com"),
  Ssn: "470806227",
})
if err != nil {
  return fmt.Errorf("error on Start: %w", err)
}

// Send the start request.
rspStart, err := client.V3.V3StartRequest(context.TODO(), &components.V3StartRequest{
  FlowType:       "desktop",
  FinalTargetURL: provesdkservergo.String("https://www.example.com"),
})
if err != nil {
  return fmt.Errorf("error on Start: %w", err)
}

The function returns the following fields:

authToken: send this to your client-side code through the Authenticate() function - it’s a JSON Web Token (JWT) tied to the current flow and used for the possession checks. It expires after 15 minutes.
correlationId: save this in your current session, then pass it in to each of the Validate(), Challenge(), and Complete() function calls of the same flow. The correlation ID ties together different system calls for the same Prove flow. It can aids in troubleshooting. The session expires in 15 minutes from when the correlation ID returns from the Start() call.
next: map of the next API call you need to make.

Return the authToken in a response to the front end.

Authenticate

Once you have the authToken, build the authenticator for both the mobile and desktop 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))
      .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

There are two functions to implement for the OTP handling - a start and a finish step. The OTP session has a two minute timeout from when it’s sent through SMS to when the customer can enter in the OTP.

To set the OTP handler, implement withOtpFallback(startStep: OtpStartStep | OtpStartStepFn, finishStep: OtpFinishStep | OtpFinishStepFn), OtpStartStep and OtpFinishStep. The JavaScript snippet has a simplified example while the TypeScript snippet explains various situations. Ensure you return an object with the field phoneNumber to the resolve() function.

Retry functionality is unavailable using OTP.

function otpStart(phoneNumberNeeded, phoneValidationError) {
  return new Promise((resolve, reject) => {
    if (phoneNumberNeeded) {
      var val = prompt("Enter phone number:");
      let input = {
        phoneNumber: val,
      };
      resolve(input);
    } else {
      resolve(null);
    }
  });
}

Call the resolve(input: OtpStartInput) method to return the collected phone number to the SDK.

If you passed the phone number in the Start() call, call resolve(null) to communicate to the SDK you have the customer’s agreement to deliver the SMS OTP message. Ensure you return an object to resolve() function.

Call the reject("some error message") method to communicate to the SDK any issues while trying to obtain the phone number. Report an error if the customer cancels the SMS OTP transaction or presses the back button to leave the SMS OTP start step screen.

function otpFinish(err) {
  return new Promise((resolve, reject) => {
    if (err) {
      console.log(err);
    } else {
      var val = prompt(`Enter your OTP:`);

      let result = {
        input: {
          otp: val,
        },
        resultType: 0,
      };

      resolve(result);
    }
  });
}

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.

Call the reject("some error message") method to communicate to the SDK any issues while trying to obtain the OTP value. Report an error if the customer cancels the SMS OTP transaction or presses the back button to exit out of the SMS OTP finish step screen.

Also call the resolve(result: OtpFinishResult) method to request a SMS OTP message in which the result variable has OnResendOtp as value for OtpFinishResultType. The SDK initiates a OtpStartStep.execute() call to allow the mobile app to restart the phone number collection logic. You can send up to three OTPs during the same authentication session.

Configure Instant Link

There is one function to configure for Instant Link. The Instant Link session has a three minute timeout from when it’s sent through SMS to when the customer can selects it.

To set the Instant Link handler, withInstantLinkFallback(startStep: InstantLinkStartStep | InstantLinkStartStepFn) requires implementing the InstantLinkStartStep interface. The JavaScript snippet has a simplified example while the TypeScript snippet explains various situations. Ensure you return an object with the field phoneNumber to the resolve() function.

function instantLink(phoneNumberNeeded, phoneValidationError) {
  return new Promise((resolve, reject) => {
    if (phoneNumberNeeded) {
      var val = prompt("Enter phone number:");
      let input = {
        phoneNumber: val,
      };
      resolve(input);
    } else {
      resolve(null);
    }
  });
}

Call the resolve(input: InstantStartInput) method to return the collected phone number to the SDK.

Call the reject("some error message") method to communicate to the SDK any issues while trying to obtain the phone number. Report an error if the customer cancels the Instant Link transaction or presses the back button to leave the Instant Link start step dialog.

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.prove-auth.proveapis.com and wss: device.prove-auth.proveapis.com.

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

Retry functionality is unavailable using OTP.

function otpStart(phoneNumberNeeded, phoneValidationError) {
  return new Promise((resolve, reject) => {
    if (phoneNumberNeeded) {
      var val = prompt("Enter phone number:");
      let input = {
        phoneNumber: val,
      };
      resolve(input);
    } else {
      resolve(null);
    }
  });
}

Call the resolve(input: OtpStartInput) method to return the collected phone number to the SDK.

function otpFinish(err) {
  return new Promise((resolve, reject) => {
    if (err) {
      console.log(err);
    } else {
      var val = prompt(`Enter your OTP:`);

      let result = {
        input: {
          otp: val,
        },
        resultType: 0,
      };

      resolve(result);
    }
  });
}

Configure Instant Link

There is one function to configure for Instant Link. The Instant Link session has a three minute timeout from when it’s sent through SMS to when the customer can selects it.

function instantLink(phoneNumberNeeded, phoneValidationError) {
  return new Promise((resolve, reject) => {
    if (phoneNumberNeeded) {
      var val = prompt("Enter phone number:");
      let input = {
        phoneNumber: val,
      };
      resolve(input);
    } else {
      resolve(null);
    }
  });
}

Call the resolve(input: InstantStartInput) method to return the collected phone number to the SDK.

If you’re using Content Security Policy headers, ensure you allow wss: device.uat.prove-auth.proveapis.com and wss: device.prove-auth.proveapis.com.

Java

// Object implementing AuthFinishStep interface
AuthFinishStep authFinishStep = new AuthFinishStep() {
   ...
};

// Objects implementing OtpStartStep/OtpFinishStep interfaces
OtpStartStep otpStartStep = new OtpStartStep() {
  ...
};

OtpFinishStep otpFinishStep = new OtpFinishStep() {
  ...
};

ProveAuth proveAuth = ProveAuth.builder()
    .withAuthFinishStep(authId -> verify(authId)) // verify(authId) call defined in #Validate the Mobile Phone section
    .withOtpFallback(otpStartStep, otpFinishStep)
    .withContext(this)
    .build();

The cellular data connection can sometimes be unavailable during testing. The Builder class offers a withTestMode(boolean testMode) method, which permits simulated successful session results while connected to a Wi-Fi network only (without a cellular data connection available). Testing using a Wi-Fi connection is useful in the Sandbox environment.

Java

ProveAuth proveAuth = ProveAuth.builder()
    .withAuthFinishStep(authId -> verify(authId))
    .withOtpFallback(otpStartStep, otpFinishStep)
    .withContext(this)
    .withTestMode(true) // Test mode flag
    .build();

The ProveAuth object is thread safe. You can use it as a singleton. Most Prove Auth methods are blocking and therefore can’t execute in the main application thread. The application employs an executor service with a minimum of two threads to manage threads due to the SDK’s ability to process concurrent blocking requests.

Java

public class MyAuthenticator {
    private final MyBackendClient backend = new MyBackendClient(); // Backend API client

    private final AuthFinishStep authFinishStep = new AuthFinishStep() {
        @Override
        void execute(String authId) {
            try {
                AuthFinishResponse response = backend.authFinish("My App", authId);
                ... // Check the authentication status returned in the response
            } catch (IOException e) {
                String failureCause = e.getCause() != null ? e.getCause().getMessage() : "Failed to request authentication results";
                // Authentication failed due to request failure
            }
        }
    };

    private ProveAuth proveAuth;

    public MyAuthenticator(Context context) {
        proveAuth = ProveAuth.builder()
          .withAuthFinishStep(authFinishStep)
          .withOtpFallback(otpStartStep, otpFinishStep)
          .withContext(context)
          .build();
    }

    public void authenticate() throws IOException, ProveAuthException {
        AuthStartResponse response = backend.authStart("My Prove Auth App");

        proveAuth.authenticate(response.getAuthToken());
    }
}

Configure OTP

You need to implement two functions for the one-time password (OTP) handling - a start and a finish step.

You can’t use retry functionality in OTP.

To set the OTP handlers, implement OtpStartStep and OtpFinishStep. The Java snippet has an example.

OtpStartStep example:

Java

package com.prove.android_sample_app;

import android.app.Activity;
import android.content.Context;
import android.content.Intent;

import androidx.activity.result.ActivityResultLauncher;
import androidx.activity.result.ActivityResultRegistry;
import androidx.activity.result.contract.ActivityResultContracts;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.lifecycle.DefaultLifecycleObserver;
import androidx.lifecycle.LifecycleOwner;

import com.prove.sdk.proveauth.OtpStartInput;
import com.prove.sdk.proveauth.OtpStartStepCallback;
import com.prove.sdk.proveauth.PhoneNumberValidationException;
import com.prove.sdk.proveauth.ProveAuthException;

import java.util.concurrent.atomic.AtomicReference;

public class OtpStartStep implements
        com.prove.sdk.proveauth.OtpStartStep,
        DefaultLifecycleObserver {
    public static final String OTP_START_STEP_KEY = "OtpStartStep";
    private final ActivityResultRegistry registry;
    private ActivityResultLauncher<Intent> launcher;
    private final Context context;
    private final AtomicReference<OtpStartStepCallback> otpStartStepCallbackRef =
            new AtomicReference<>();

    public OtpStartStep(Context context, @NonNull ActivityResultRegistry registry) {
        this.context = context;
        this.registry = registry;
    }

    @Override
    public void execute(boolean phoneNumberNeeded, @Nullable ProveAuthException exception,
            OtpStartStepCallback otpStartStepCallback) {
        if (exception instanceof PhoneNumberValidationException) {
            otpStartStepCallbackRef.set(otpStartStepCallback);
            Intent intent = new Intent(context, OtpPhoneNumberInputActivity.class);
            intent.putExtra(IntentExtraFields.OTP_ERROR,
                    "Phone number is invalid, please try again.");
            launcher.launch(intent);
            return;
        }

        if (phoneNumberNeeded) {
            // We need to store callback object, it will be needed to complete this activity
            // by calling it with the results.
            otpStartStepCallbackRef.set(otpStartStepCallback);
            Intent intent = new Intent(context, OtpPhoneNumberInputActivity.class);
            launcher.launch(intent);
        } else {
            otpStartStepCallback.onSuccess(new OtpStartInput(""));
        }
    }

    public void onCreate(@NonNull LifecycleOwner owner) {
        launcher = registry.register(OTP_START_STEP_KEY, owner,
                new ActivityResultContracts.StartActivityForResult(),
                result -> {
                    OtpStartStepCallback callback = otpStartStepCallbackRef.get();
                    if (callback == null) {
                        return;
                    }

                    if (result.getResultCode() == Activity.RESULT_OK) {
                        Intent intent = result.getData();
                        if (intent != null) {
                            String phoneNumber = intent.getStringExtra(
                                    IntentExtraFields.OTP_PHONE_NUMBER_FIELD);
                            callback.onSuccess(new OtpStartInput(phoneNumber));
                        } else {
                            callback.onError();
                        }
                    } else {
                        callback.onError();
                    }
                });
    }
}

OtpFinishStep example:

Java

import android.app.Activity;
import android.content.Context;
import android.content.Intent;
import android.util.Log;

import androidx.activity.result.ActivityResultLauncher;
import androidx.activity.result.ActivityResultRegistry;
import androidx.activity.result.contract.ActivityResultContracts;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.lifecycle.DefaultLifecycleObserver;
import androidx.lifecycle.LifecycleOwner;

import com.prove.sdk.proveauth.OtpFinishInput;
import com.prove.sdk.proveauth.OtpFinishStepCallback;
import com.prove.sdk.proveauth.OtpValidationException;
import com.prove.sdk.proveauth.ProveAuthException;

import java.util.concurrent.atomic.AtomicReference;

public class OtpFinishStep implements
        com.prove.sdk.proveauth.OtpFinishStep,
        DefaultLifecycleObserver {
    public static final String OTP_FINISH_STEP_KEY = "OtpFinishStep";
    private final ActivityResultRegistry registry;
    private ActivityResultLauncher<Intent> launcher;
    private final Context context;
    private final AtomicReference<OtpFinishStepCallback> otpFinishStepCallbackRef =
            new AtomicReference<>();

    public OtpFinishStep(Context context, @NonNull ActivityResultRegistry registry) {
        this.context = context;
        this.registry = registry;
    }

    @Override
    public void execute(@Nullable ProveAuthException otpException,
            OtpFinishStepCallback otpFinishStepCallback) {
        // We need to store callback object, it will be needed to complete this activity
        // by calling it with the results.
        otpFinishStepCallbackRef.set(otpFinishStepCallback);
        if (otpException instanceof OtpValidationException) {
            Log.e("OtpFinishStep", "found otp errors", e);
            return;
        }
        Intent intent = new Intent(context, OtpCodeInputActivity.class);
        launcher.launch(intent);
    }

    public void onCreate(@NonNull LifecycleOwner owner) {
        launcher = registry.register(OTP_FINISH_STEP_KEY, owner,
                new ActivityResultContracts.StartActivityForResult(),
                result -> {
                    OtpFinishStepCallback callback = otpFinishStepCallbackRef.get();
                    if (callback == null) {
                        return;
                    }

                    if (result.getResultCode() == Activity.RESULT_OK) {
                        Intent intent = result.getData();
                        if (intent != null) {
                            String code = intent.getStringExtra(
                                        IntentExtraFields.OTP_CODE_FIELD);
                            callback.onSuccess(new OtpFinishInput(code));
                            return;
                        }
                    }
                    callback.onError();
                });
    }
}

Swift

// Object implementing ProveAuthFinishStep protocols
let finishStep = FinishAuthStep()

// Objects implementing OtpStartStep/OtpFinishStep protocols
let otpStartStep = MobileOtpStartStep()
let otpFinishStep = MobileOtpFinishStep()

let proveAuthSdk: ProveAuth
proveAuthSdk = ProveAuth.builder(authFinish: finishStep)
  .withOtpFallback(otpStart: otpStartStep, otpFinish: otpFinishStep)
  .build()

In the event a cellular data connection is unavailable during testing, use the Builder class. It permits simulated successful session results while connected to a Wi-Fi network. Testing using a Wi-Fi connection is useful in the Sandbox environment.

Swift

proveAuthSdk = ProveAuth.builder(authFinish: finishStep)
  .withMobileAuthTestMode() // Test mode flag
  .build()

The Prove Auth object is thread safe and used as a singleton. Most Prove Auth methods are blocking and therefore can’t execute in the main application thread. The application employs an executor service with a minimum of two threads to manage threads due to the SDK’s ability to process concurrent blocking requests.

Swift

// authToken retrieved from your server via StartAuthRequest
proveAuthSdk.authenticate(authToken) { error in
  DispatchQueue.main.async {
    self.messages.finalResultMessage = "ProveAuth.authenticate returned error: \(error.localizedDescription)"
    print(self.messages.finalResultMessage)
  }
}

Configure OTP

You can implement two functions for the OTP handling - a start and a finish step.

To set the OTP handlers, implement OtpStartStep and OtpFinishStep interfaces. The Swift snippet has an example.

Retry functionality is unavailable in OTP.

OtpStartStep example:

Swift

import Foundation
import ProveAuth
import SwiftUI

// Implementation of OtpStartStep protocol
class MobileOtpStartStep: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

    init(sheetObservable: SheetObservable){
        self.sheetObservable = sheetObservable
    }

    // ProveAuth SDK calls this method when it is time to collect a customer's phone number for SMS OTP and/or obtain
    // the customer's confirmation to initiate the SMS message to the phone number provided
    // 'phoneNumberNeeded' argument indicates whether mobile app needs to collect the phone number
    func execute(phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback) {
        // here - signal to ContentView to display OtpStartView
        DispatchQueue.main.async {
            // SDK returns phoneValidationError if the phone number provided is invalid or blocked
            if case .phoneNumberValidationError = phoneValidationError {
                self.sheetObservable.isPhoneValidationError = true
            } else {
                self.sheetObservable.isPhoneValidationError = false
            }
            self.sheetObservable.isOtpStartActive = true
            self.sheetObservable.isPhoneNumberNeeded = phoneNumberNeeded
            self.callback = callback
        }
    }

    // Here - return collected phone number string to SDK
    func handlePhoneNumber(phoneNumber: String? = nil) {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }
        if let phoneNumber = phoneNumber {
            let otpStartInput = OtpStartInput(phoneNumber: phoneNumber)
            // This is how you pass collected phone number to SDK
            callback.onSuccess(input: otpStartInput)
            return
        }
        // If phoneNumberNeeded = false (in the OtpStartStep.execute) and phone number was already provided in the initial server-to-server call to /start endpoint
        // Then return nil back to SDK, Prove Auth server already got the phone number
        // calling onSuccess here indicates that the customer's confirmation to send SMS was obtained
        callback.onSuccess(input: nil)
    }

    // Here - communicate to the SDK any issues while trying to obtain the phone number.
    // Error should be reported if the customer explicitly cancels the SMS OTP transaction or presses the back button to exit out the SMS OTP start step screen.
    func handleOtpStartError() {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

OtpFinishStep example:

Swift

import Foundation
import SwiftUI
import ProveAuth

// Implementation of OtpFinishStep protocol
class MobileOtpFinishStep: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

    init(sheetObservable: SheetObservable){
        self.sheetObservable = sheetObservable
    }
    // SDK calls this method when it is time to collect OTP value delivered in the SMS message
    // otpError will be returned if OTP value was incorrect
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // here - signal to ContentView to display OtpFinishView
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Here - return the OTP value to the SDK
    func handleOtp(_ otp: String) {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }
        let otpFinishInput = OtpFinishInput(otp: otp)
        callback.onSuccess(input: otpFinishInput)
    }

    // Here - communicate to the SDK any issues while trying to obtain the OTP value.
    // Error should be reported if the customer explicitly cancels the SMS OTP transaction or presses the back button to exit out the SMS OTP finish step screen.
    func handleOtpFinishError() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

Mobile Number Reentry

To enable mobile number reentry in the flow, contact your Prove representative.

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 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. In the event of cancellation, 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;
}

// 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;
}

Java

// Send a verify request to get return customer information.
void verify(String: authId) {
  YourBackendClient backend = new YourBackendClient(); // Backend API client

  // Build your VerifyRequest object
  VerifyRequest verifyRequest = new VerifyRequest(authId, ...);

  // Send a verify request to your backend server to get return customer information.
  VerifyResponse response = backend.verify(verifyRequest);

  // TODO: define your VerifyResponse object to parse customer information from the response
  String firstName = response.getFirstName();
  String lastName = response.getLastName();

  // Pre-fill customer information to your Android App UI, for example:
  firstNameEditText.setText(firstName);
  lastNameEditText.setText(lastName);
}

Swift

  // Send a verify request to get return customer information.
  // The below example uses native iOS URLSession, but any other
  // alternative networking approaches should also work
  func verify(String: authId, completion: @escaping (Error?) -> Void) {
      guard let url = URL(string: "\(backendUrl)/verify") else {
          completion(URLError(.badURL))
          return
      }
      // Create the request
      var request = URLRequest(url: url)
      request.httpMethod = "POST"
      request.addValue("application/json", forHTTPHeaderField: "Accept")
      request.addValue("application/json", forHTTPHeaderField: "Content-Type")
      // Set up the request body (empty JSON object) - authId is not needed so you can ignore.
      let body: [String: Any] = ["authId": authId]
      do {
          request.httpBody = try JSONSerialization.data(withJSONObject: body, options: \[])
      } catch {
          completion(error)
          return
      }
      // Perform the request
      let task = URLSession.shared.dataTask(with: request) { \_, response, error in
          if let error = error {
              completion(error)
              return
          }
          // Parse the response
          do {
              if let json = try JSONSerialization.jsonObject(with: data, options: \[]) as? [String: Any],
                 let firstName = json["firstName"] as? String,
                 let lastName = json["lastName"] as? String {
                  // Update the UI on the main thread
                  DispatchQueue.main.async {
                      // Update your UI with the pre-fill customer information
                      // For example, assuming you have IBOutlet references for your text fields
                      self.firstNameInput.text = firstName
                      self.lastNameInput.text = lastName
                  }
                  completion(nil)
              } else {
                  let parsingError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey: "Failed to parse JSON"])
                  completion(parsingError)
              }
          } catch {
              completion(error)
          }
      }
      // Start the network call
      task.resume()
  }

Validate Mobile Phone

Once the possession checks finish on the mobile device, the finish handler on the client-side SDK executes. You then make a request to your server such as POST /verify to make the next call in the flow to the Validate() function.

This function requires the Correlation ID which is returned by the Start() function.

rspValidate, err := client.V3.V3ValidateRequest(context.TODO(), &components.V3ValidateRequest{
	CorrelationID: rspStart.V3StartResponse.CorrelationID,
})
if err != nil {
    return fmt.Errorf("error on Validate(): %w", err)
}

The function returns the following fields:

success: true if customer info returned.
individual: customer information in a map.
next: map of the next API you need to call you need to make.

If success=true, return the customer information in a response to the front end to prefill the form.

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;
}

// 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;
}

Java

  // Send request to the backend to verify customer information.
  SendInfoResponse sendInfo(String firstName, String lastName) {
    YourBackendClient backend = new YourBackendClient(); // Backend API client

    // TODO: Build your SendInfoRequest object
    SendInfoRequest sendInfoRequest = new SendInfoRequest(firstName, lastName, ...);

    // Send a sendInfoRequest to your backend server to get return customer information.
    SendInfoResponse response = backend.verify(sendInfoRequest);

    // TODO: define your own SendInfoResponse object to parse the response
    return response;
  }

Swift

  // Send request to the backend to verify customer information.
  // The below example uses native iOS URLSession, but any other
  // alternative networking approaches should also work
  func sendInfo(firstName: String, lastName: String, completion: @escaping (Result\<[String:Any], Error>) -> Void) {
      guard let url = URL(string: "\(backendUrl)/finish") else {
          completion(.failure(URLError(.badURL)))
          return
      }
      var request = URLRequest(url: url)
      request.httpMethod = "POST"
      request.addValue("application/json", forHTTPHeaderField: "Accept")
      request.addValue("application/json", forHTTPHeaderField: "Content-Type")
      // Set up the request body
      let body: [String: Any] = [
          "firstName": firstName,
          "lastName": lastName
      ]
      do {
          request.httpBody = try JSONSerialization.data(withJSONObject: body, options: \[])
      } catch {
          completion(.failure(error))
          return
      }
      let task = URLSession.shared.dataTask(with: request) { \_, response, error in
          // Handle network or connection errors
          if let error = error {
              completion(.failure(error))
              return
          }
          do {
              if let results = try JSONSerialization.jsonObject(with: data, options: \[]) as? [String: Any] {
                  completion(.success(results))
              } else {
                  let parsingError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey : "Failed to parse JSON or authToken is missing"])
                  completion(.failure(parsingError))
              }
          } catch {
              completion(.failure(error))
          }
      }
      // Start the network call
      task.resume()
  }

Call the Complete Endpoint

This function is the final call in the flow that verifies the customer information.

This function takes these required parameters:

Correlation ID: this is the ID returned by the Start() function.
Individual: customer information in a map.

When implementing the KYC add-on, you need to pass in first name, last name, DOB, and SSN (or address) to ensure you receive back the KYC and CIP fields. If applicable, the following reason codes will return in Production:

DI - this identity is associated with a death indicator.
CF - The address matches the address of a U.S. correctional facility.
PO - The address was classified as a PO Box.

Refer to the Complete API reference and select “Response with KYC - 0 hits” for an example response.

rspComplete, err := client.V3.V3CompleteRequest(context.TODO(), &components.V3CompleteRequest{
	CorrelationID: rspStart.V3StartResponse.CorrelationID,
	Individual: components.Individual{
		FirstName: provesdkservergo.String("Tod"),
		LastName:  provesdkservergo.String("Weedall"),
		Addresses: []components.AddressEntry{
			{
				Address:    provesdkservergo.String("39 South Trail"),
				City:       provesdkservergo.String("San Antonio"),
				Region:     provesdkservergo.String("TX"),
				PostalCode: provesdkservergo.String("78285"),
			},
		},
		Ssn: provesdkservergo.String("565228370"),
		Dob: provesdkservergo.String("1984-12-10"),
		EmailAddresses: []string{
			"[email protected]",
		},
	},
})
if err != nil {
	return fmt.Errorf("error on Complete(): %w", err)
}

The function returns the following fields:

Success: true if customer information returned.
Next: map of the next API call you need to make, in this case, Done.

You can then respond to the front end with the results of the customer verification.

Test Your Prove Implementation

Next, reference the Sandbox test scenarios to test users and simulate different behaviors encountered in production.

Production Launch

To launch in Production, please contact your Prove representative.

Get Started

Prove Pre-Fill®

Prove Identity®

Prove Verified Users

Prove Unify

Prove Identity Manager

Stay Informed

Implementation Guide

Prerequisites

Implement Prove Pre-Fill

Configure OTP

Configure Instant Link

Configure OTP

Configure Instant Link

Configure OTP

Configure OTP

Test Your Prove Implementation

Get Started

Prove Pre-Fill®

Prove Identity®

Prove Verified Users

Prove Unify

Prove Identity Manager

Stay Informed

​Prerequisites

​Implement Prove Pre-Fill

​Configure OTP

​Configure Instant Link

​Configure OTP

​Configure Instant Link

​Configure OTP

​Configure OTP

​Test Your Prove Implementation

Prerequisites

Implement Prove Pre-Fill

Configure OTP

Configure Instant Link

Configure OTP

Configure Instant Link

Configure OTP

Configure OTP

Test Your Prove Implementation