Authentication Overview

How to implement

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

Using Prove's Possession
Using Customer-Supplied Possession

Flowchart showing the Prove authentication overview with Mobile Auth and OTP fallback

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, 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()

When using the Android SDK, set mobile as the possessionType.

When using the iOS SDK, set mobile as the possessionType.

Initialize the Flow

Send a request to the back end server with the phone number, possession type, and client request ID 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.

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

Follow these instructions if implementing MobileAuth and collecting the phone number only if MobileAuth fails. This will implement OTP without allowing for SMS resends and phone number changes. If you do want those capabilities, please reference the subsequent tabs (Resend, Retry OTP, and Phone Number Change).In the start step, call the resolve(input: OtpStartInput) method to return the collected phone number to the SDK.

function otpStartStep(phoneNumberNeeded, phoneValidationError) {
  return new Promise((resolve, reject) => {
    // If no phone number is needed, then don't prompt the user.
    if (!phoneNumberNeeded) {
      resolve(null);

      return;
    }

    // If error message is found around phone number, handle it.
    // The `phoneValidationError` is ONLY available when `phoneNumberNeeded`
    // has a value.
    if (phoneValidationError) {
      // Set to a variable and display it in a field.
      // In this example, we don't do anything with the error.
      var someErrorMessage = phoneValidationError.message;
    }

    // Prompt the user for the phone number.
    var input = prompt('Enter phone number:');
    if (input) {
      // If the input is valid and the user clicked `OK`, return the phone
      // number.
      resolve({
        phoneNumber: input,
      });
    } else {
      // Else, exit the flow.
      reject('phone invalid or user cancelled');
    }
  });
}

The finish step is implemented the same as the previous tab:

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

Follow these instructions to allow the customer to request a new OTP via SMS using the same phone number. There is a max of three send attempts including the initial message.The start step is implemented the same as the previous tab:

function otpStartStep(phoneNumberNeeded, phoneValidationError) {
  return new Promise((resolve, reject) => {
    // If no phone number is needed, then don't prompt the user.
    if (!phoneNumberNeeded) {
      resolve(null);

      return;
    }

    // If error message is found around phone number, handle it.
    // The `phoneValidationError` is ONLY available when `phoneNumberNeeded`
    // has a value.
    if (phoneValidationError) {
      // Set to a variable and display it in a field.
      // In this example, we don't do anything with the error.
      var someErrorMessage = phoneValidationError.message;
    }

    // Prompt the user for the phone number.
    var input = prompt('Enter phone number:');
    if (input) {
      // If the input is valid and the user clicked `OK`, return the phone
      // number.
      resolve({
        phoneNumber: input,
      });
    } else {
      // Else, exit the flow.
      reject('phone invalid or user cancelled');
    }
  });
}

You can then send a new OTP SMS to the same phone number by implementing the finish step like this:

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) {
      // If `Cancel`, then resend to the same phone number.
      resolve({
        resultType: 1, // OnResendOtp enum type = 1
      });

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

Follow these instructions to allow the customer to re-enter the OTP PIN if they type it wrong. There is a max of 3 attempts. To implement this functionality, you also need to pass in allowOTPRetry=true to the /v3/start endpoint.The start step is implemented the same as either of the the previous tabs - no client side code changes necessary:

function otpStartStep(phoneNumberNeeded, phoneValidationError) {
  return new Promise((resolve, reject) => {
    // If no phone number is needed, then don't prompt the user.
    if (!phoneNumberNeeded) {
      resolve(null);

      return;
    }

    // If error message is found around phone number, handle it.
    // The `phoneValidationError` is ONLY available when `phoneNumberNeeded`
    // has a value.
    if (phoneValidationError) {
      // Set to a variable and display it in a field.
      // In this example, we don't do anything with the error.
      var someErrorMessage = phoneValidationError.message;
    }

    // Prompt the user for the phone number.
    var input = prompt('Enter phone number:');
    if (input) {
      // If the input is valid and the user clicked `OK`, return the phone
      // number.
      resolve({
        phoneNumber: input,
      });
    } else {
      // Else, exit the flow.
      reject('phone invalid or user cancelled');
    }
  });
}

The finish step is implemented the same as either of the the previous tabs - no client side code changes necessary. If the OTP is invalid, the finish step will be called again to prompt the user for a new input. Once the max attempts is reached, the AuthFinish function will be called.

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

Follow these instructions to allow the customer to re-enter their phone number. There is a max of three entries/send attempts.

Manual Request RequiredTo enable phone number change capabilities on your credentials, contact your Prove representative.

The start step is implemented the same as the previous tab:

function otpStartStep(phoneNumberNeeded, phoneValidationError) {
  return new Promise((resolve, reject) => {
    // If no phone number is needed, then don't prompt the user.
    if (!phoneNumberNeeded) {
      resolve(null);

      return;
    }

    // If error message is found around phone number, handle it.
    // The `phoneValidationError` is ONLY available when `phoneNumberNeeded`
    // has a value.
    if (phoneValidationError) {
      // Set to a variable and display it in a field.
      // In this example, we don't do anything with the error.
      var someErrorMessage = phoneValidationError.message;
    }

    // Prompt the user for the phone number.
    var input = prompt('Enter phone number:');
    if (input) {
      // If the input is valid and the user clicked `OK`, return the phone
      // number.
      resolve({
        phoneNumber: input,
      });
    } else {
      // Else, exit the flow.
      reject('phone invalid or user cancelled');
    }
  });
}

You can prompt for a new phone numberby implementing the finish step like this:

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) {
      // If `Cancel`, then trigger the otpStartStep to re-prompt for
      // phone number.
      resolve({
        resultType: 2, // OnMobileNumberChange enum type = 2
      });

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

Configure Instant Link

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

Follow these instructions if implementing MobileAuth and collecting the phone number for desktop. This will implement Instant Link without allowing for SMS resends and phone number changes. If you do want those capabilities, please reference the subsequent tabs (Resend and Phone Number Change).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.

function instantLinkStartStep(phoneNumberNeeded, phoneValidationError) {
  return new Promise((resolve, reject) => {
    // If no phone number is needed, then don't prompt the user.
    if (!phoneNumberNeeded) {
      resolve(null);

      return;
    }

    // If error message is found around phone number, handle it.
    // The `phoneValidationError` is ONLY available when `phoneNumberNeeded`
    // has a value.
    if (phoneValidationError) {
      // Set to a variable and display it in a field.
      // In this example, we don't do anything with the error.
      var someErrorMessage = phoneValidationError.message;
    }

    // Prompt the user for the phone number.
    var input = prompt('Enter phone number:');
    if (input) {
      // If the input is valid and the user clicked `OK`, return the phone
      // number.
      resolve({
        phoneNumber: input,
      });
    } else {
      // Else, exit the flow.
      reject('phone invalid or user cancelled');
    }
  });
}

Follow these instructions to allow the customer to request a new SMS using the same phone number. There is a max of three send attempts including the initial message.The start step is implemented the same as the previous tab:

function instantLinkStartStep(phoneNumberNeeded, phoneValidationError) {
  return new Promise((resolve, reject) => {
    // If no phone number is needed, then don't prompt the user.
    if (!phoneNumberNeeded) {
      resolve(null);

      return;
    }

    // If error message is found around phone number, handle it.
    // The `phoneValidationError` is ONLY available when `phoneNumberNeeded`
    // has a value.
    if (phoneValidationError) {
      // Set to a variable and display it in a field.
      // In this example, we don't do anything with the error.
      var someErrorMessage = phoneValidationError.message;
    }

    // Prompt the user for the phone number.
    var input = prompt('Enter phone number:');
    if (input) {
      // If the input is valid and the user clicked `OK`, return the phone
      // number.
      resolve({
        phoneNumber: input,
      });
    } else {
      // Else, exit the flow.
      reject('phone invalid or user cancelled');
    }
  });
}

You can then send a new Instant Link SMS to the same phone number by implementing the InstantLinkRetryStep interface, for example:

function instantLinkRetryStep() {
  return new Promise((resolve, reject) => {
    // There are multiple return options:
    // - resolve(0): request resend to the same phone number
    // - reject('user clicked cancel'): error out of the possession flow

    // Prompt the user for the phone number.
    // Typically, this is a page that is automatically closed or redirected
    // once the `AuthFinish` function is called. We are simplifying it by
    // requiring an input.
    var input = confirm('Did you receive a text message?');
    if (input) {
      // If `OK`, close the modal.
      return;
    }

    // Else `Cancel`, then resend to the same phone number.
    resolve(0);
  });
}

Follow these instructions to allow the customer to re-enter their phone number. There is a max of three entries/send attempts.

Manual Request RequiredTo enable phone number change capabilities on your credentials, contact your Prove representative.

The start step is implemented the same as the previous tab:

function instantLinkStartStep(phoneNumberNeeded, phoneValidationError) {
  return new Promise((resolve, reject) => {
    // If no phone number is needed, then don't prompt the user.
    if (!phoneNumberNeeded) {
      resolve(null);

      return;
    }

    // If error message is found around phone number, handle it.
    // The `phoneValidationError` is ONLY available when `phoneNumberNeeded`
    // has a value.
    if (phoneValidationError) {
      // Set to a variable and display it in a field.
      // In this example, we don't do anything with the error.
      var someErrorMessage = phoneValidationError.message;
    }

    // Prompt the user for the phone number.
    var input = prompt('Enter phone number:');
    if (input) {
      // If the input is valid and the user clicked `OK`, return the phone
      // number.
      resolve({
        phoneNumber: input,
      });
    } else {
      // Else, exit the flow.
      reject('phone invalid or user cancelled');
    }
  });
}

You can prompt for a new phone number by implementing the InstantLinkRetryStep interface, for example:

function instantLinkRetryStep() {
  return new Promise((resolve, reject) => {
    // There are multiple return options:
    // - resolve(0): request resend to the same phone number
    // - resolve(1): request phone number change/re-prompt
    // - reject('user clicked cancel'): error out of the possession flow

    // Prompt the user for the phone number.
    // Typically, this is a page that is automatically closed or redirected
    // once the `AuthFinish` function is called. We are simplifying it by
    // requiring an input.
    var input = confirm('Did you receive a text message?');
    if (input) {
      // If `OK`, close the modal.
      return;
    }

    // Else `Cancel`, then trigger the instantLinkStartStep to re-prompt for
    // phone number.
    resolve(1);
  });
}

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.

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

To use the Resend/Retry/Phone Change features, you need to install the Android SDK version 6.5.0 or later.

To set the One-Time Password (OTP) handler, withOtpFallback(otpStart: otpStartStep, otpFinish: otpFinishStep), requires implementing the OtpStartStep and OtpFinishStep.The OTP session has a two minute timeout from when it’s sent through 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 OtpStartStepCallback.onSuccess(OtpStartInput); to communicate to the SDK you have the customer’s agreement to deliver the SMS message. Ensure you return an instance of OtpStartInput with empty string or null to OtpStartStepCallback.onSuccess() function.

Java

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

public class NoPromptStart implements OtpStartStep {
    @Override
    public void execute(boolean phoneNumberNeeded, ProveAuthException otpException,
            OtpStartStepCallback callback) {
        // No phone number needed, no need to ask end user for input.
        callback.onSuccess(new OtpStartInput(""));
    }

}

Call the OtpStartStepCallback.onError(); 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 OtpFinishStepCallback.onSuccess(OtpFinishInput); method to return the collected OTP value wrapped in OtpFinishInput.

Java

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

public class NoPromptFinish implements OtpFinishStep {
    @Override
    public void execute(@Nullable ProveAuthException otpException,
            OtpFinishStepCallback otpFinishStepCallback) {
        // If error message is found, handle it.
        if (otpException instanceof OtpValidationException) {
            // Set to a variable and display it in a field.
            // In this example, we don't do anything with the error.
            String errorMsg = otpException.getMessage();
        }

        try {
            // Prompt the user for OTP delivered by SMS. You can build UI to provide
            // best UX based on your application and business logic, here we simplify to a
            // generic function named promptForOtpCode which gives us the OTP code.
            String otpCode = promptForOtpCode();
            otpFinishStepCallback.onSuccess(new OtpFinishInput(otpCode));
        } catch (Exception e) {
            // if any issue with the OTP collection from the end user or the user wants to cancel
            // then call onError to exit the flow. In this example we simplify it as catching
            // an exception.
            otpFinishStepCallback.onError();
        }
    }

}

Follow these instructions if implementing MobileAuth and collecting the phone number only if MobileAuth fails. This will implement OTP without allowing for SMS resends and phone number changes. If you do want those capabilities, please reference the subsequent tabs (Resend, Retry OTP, and Phone Number Change).In the start step, call the OtpStartStepCallback.onSuccess(OtpStartInput); method to return the collected phone number to the SDK.

Java

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

public class PromptStart implements OtpStartStep {
    @Override
    public void execute(boolean phoneNumberNeeded, @Nullable ProveAuthException otpException,
            OtpStartStepCallback callback) {
        // If phone number is needed, need to ask the end user for phone number input.
        if (phoneNumberNeeded) {
            // If error message is found around phone number, handle it.
            // The `PhoneNumberValidationException` is ONLY available when `phoneNumberNeeded`
            // has a value.
            if (otpException instanceof PhoneNumberValidationException) {
                // Set to a variable and display it in a field.
                // In this example, we don't do anything with the error.
                String errorMsg = otpException.getMessage();
            }

            try {
                // Prompt the user for phone number to receive OTP SMS. You can build UI to provide
                // best UX based on your application and business logic, here we simplify to a
                // generic function named promptForPhoneNumber which gives us the collected
                // phone number.
                String phoneNumber = promptForPhoneNumber();
                callback.onSuccess(new OtpStartInput(phoneNumber));
            } catch (Exception e) {
                // if any issue with the phone number collection from the end user or the user
                // wants to cancel then call onError to exit the flow.
                // In this example we simplify it as catching an exception.
                callback.onError();
            }
        } else {
            // No phone number needed, no need to ask end user for input.
            callback.onSuccess(new OtpStartInput(""));
        }
    }

}

The finish step is implemented the same as the previous tab:

Java

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

public class NoPromptFinish implements OtpFinishStep {
    @Override
    public void execute(@Nullable ProveAuthException otpException,
            OtpFinishStepCallback otpFinishStepCallback) {
        // If error message is found, handle it.
        if (otpException instanceof OtpValidationException) {
            // Set to a variable and display it in a field.
            // In this example, we don't do anything with the error.
            String errorMsg = otpException.getMessage();
        }

        try {
            // Prompt the user for OTP delivered by SMS. You can build UI to provide
            // best UX based on your application and business logic, here we simplify to a
            // generic function named promptForOtpCode which gives us the OTP code.
            String otpCode = promptForOtpCode();
            otpFinishStepCallback.onSuccess(new OtpFinishInput(otpCode));
        } catch (Exception e) {
            // if any issue with the OTP collection from the end user or the user wants to cancel
            // then call onError to exit the flow. In this example we simplify it as catching
            // an exception.
            otpFinishStepCallback.onError();
        }
    }

}

Java

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

public class PromptStart implements OtpStartStep {
    @Override
    public void execute(boolean phoneNumberNeeded, @Nullable ProveAuthException otpException,
            OtpStartStepCallback callback) {
        // If phone number is needed, need to ask the end user for phone number input.
        if (phoneNumberNeeded) {
            // If error message is found around phone number, handle it.
            // The `PhoneNumberValidationException` is ONLY available when `phoneNumberNeeded`
            // has a value.
            if (otpException instanceof PhoneNumberValidationException) {
                // Set to a variable and display it in a field.
                // In this example, we don't do anything with the error.
                String errorMsg = otpException.getMessage();
            }

            try {
                // Prompt the user for phone number to receive OTP SMS. You can build UI to provide
                // best UX based on your application and business logic, here we simplify to a
                // generic function named promptForPhoneNumber which gives us the collected
                // phone number.
                String phoneNumber = promptForPhoneNumber();
                callback.onSuccess(new OtpStartInput(phoneNumber));
            } catch (Exception e) {
                // if any issue with the phone number collection from the end user or the user
                // wants to cancel then call onError to exit the flow.
                // In this example we simplify it as catching an exception.
                callback.onError();
            }
        } else {
            // No phone number needed, no need to ask end user for input.
            callback.onSuccess(new OtpStartInput(""));
        }
    }

}

You can then send a new OTP SMS to the same phone number by implementing the finish step like this:

Java

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

public class MultipleResendFinish implements OtpFinishStep {
    @Override
    public void execute(@Nullable ProveAuthException otpException,
            OtpFinishStepCallback otpFinishStepCallback) {
        // If error message is found, handle it.
        if (otpException instanceof OtpValidationException) {
            // Set to a variable and display it in a field.
            // In this example, we don't do anything with the error.
            String errorMsg = otpException.getMessage();
        }

        // Prompt the user for whether they received the SMS.
        if (promptForResend("Didn't receive the SMS OTP? Click resend button for a new one!")) {
            // If the end user wants to send again to the same phone number call onOtpResend().
            otpFinishStepCallback.onOtpResend();
            return;
        }

        try {
            // Prompt the user for OTP delivered by SMS. You can build UI to provide
            // best UX based on your application and business logic, here we simplify to a
            // generic function named promptForOtpCode which gives us the OTP code.
            String otpCode = promptForOtpCode();
            otpFinishStepCallback.onSuccess(new OtpFinishInput(otpCode));
        } catch (Exception e) {
            // if any issue with the OTP collection from the end user or the user wants to cancel
            // then call onError to exit the flow. In this example we simplify it as catching
            // an exception.
            otpFinishStepCallback.onError();
        }
    }

}

Java

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

public class PromptStart implements OtpStartStep {
    @Override
    public void execute(boolean phoneNumberNeeded, @Nullable ProveAuthException otpException,
            OtpStartStepCallback callback) {
        // If phone number is needed, need to ask the end user for phone number input.
        if (phoneNumberNeeded) {
            // If error message is found around phone number, handle it.
            // The `PhoneNumberValidationException` is ONLY available when `phoneNumberNeeded`
            // has a value.
            if (otpException instanceof PhoneNumberValidationException) {
                // Set to a variable and display it in a field.
                // In this example, we don't do anything with the error.
                String errorMsg = otpException.getMessage();
            }

            try {
                // Prompt the user for phone number to receive OTP SMS. You can build UI to provide
                // best UX based on your application and business logic, here we simplify to a
                // generic function named promptForPhoneNumber which gives us the collected
                // phone number.
                String phoneNumber = promptForPhoneNumber();
                callback.onSuccess(new OtpStartInput(phoneNumber));
            } catch (Exception e) {
                // if any issue with the phone number collection from the end user or the user
                // wants to cancel then call onError to exit the flow.
                // In this example we simplify it as catching an exception.
                callback.onError();
            }
        } else {
            // No phone number needed, no need to ask end user for input.
            callback.onSuccess(new OtpStartInput(""));
        }
    }

}

Java

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

public class NoPromptFinish implements OtpFinishStep {
    @Override
    public void execute(@Nullable ProveAuthException otpException,
            OtpFinishStepCallback otpFinishStepCallback) {
        // If error message is found, handle it.
        if (otpException instanceof OtpValidationException) {
            // Set to a variable and display it in a field.
            // In this example, we don't do anything with the error.
            String errorMsg = otpException.getMessage();
        }

        try {
            // Prompt the user for OTP delivered by SMS. You can build UI to provide
            // best UX based on your application and business logic, here we simplify to a
            // generic function named promptForOtpCode which gives us the OTP code.
            String otpCode = promptForOtpCode();
            otpFinishStepCallback.onSuccess(new OtpFinishInput(otpCode));
        } catch (Exception e) {
            // if any issue with the OTP collection from the end user or the user wants to cancel
            // then call onError to exit the flow. In this example we simplify it as catching
            // an exception.
            otpFinishStepCallback.onError();
        }
    }

}

Follow these instructions to allow the customer to re-enter their phone number. There is a max of three entries/send attempts.

Manual Request RequiredTo enable phone number change capabilities on your credentials, contact your Prove representative.

The start step is implemented the same as the previous tab:

Java

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

public class PromptStart implements OtpStartStep {
    @Override
    public void execute(boolean phoneNumberNeeded, @Nullable ProveAuthException otpException,
            OtpStartStepCallback callback) {
        // If phone number is needed, need to ask the end user for phone number input.
        if (phoneNumberNeeded) {
            // If error message is found around phone number, handle it.
            // The `PhoneNumberValidationException` is ONLY available when `phoneNumberNeeded`
            // has a value.
            if (otpException instanceof PhoneNumberValidationException) {
                // Set to a variable and display it in a field.
                // In this example, we don't do anything with the error.
                String errorMsg = otpException.getMessage();
            }

            try {
                // Prompt the user for phone number to receive OTP SMS. You can build UI to provide
                // best UX based on your application and business logic, here we simplify to a
                // generic function named promptForPhoneNumber which gives us the collected
                // phone number.
                String phoneNumber = promptForPhoneNumber();
                callback.onSuccess(new OtpStartInput(phoneNumber));
            } catch (Exception e) {
                // if any issue with the phone number collection from the end user or the user
                // wants to cancel then call onError to exit the flow.
                // In this example we simplify it as catching an exception.
                callback.onError();
            }
        } else {
            // No phone number needed, no need to ask end user for input.
            callback.onSuccess(new OtpStartInput(""));
        }
    }

}

You can prompt for a new phone number by implementing the finish step like this:

Java

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

public class PhoneChangeFinish implements OtpFinishStep {
    @Override
    public void execute(@Nullable ProveAuthException otpException,
            OtpFinishStepCallback otpFinishStepCallback) {
        // If error message is found, handle it.
        if (otpException instanceof OtpValidationException) {
            // Set to a variable and display it in a field.
            // In this example, we don't do anything with the error.
            String errorMsg = otpException.getMessage();
        }

        // Prompt the user for whether they received the SMS.
        if (promptForPhoneNumberChange("Didn't receive the SMS OTP? Try a different phone number.")) {
            // If the end user wants to correct the phone number already in use, or changing to a
            // different phone number to receive the future SMS OTP, call onMobileNumberChange(), and
            // the otpStartStep will re-prompt for phone number input from the end user.
            otpFinishStepCallback.onMobileNumberChange();
            return;
        }

        try {
            // Prompt the user for OTP delivered by SMS. You can build UI to provide
            // best UX based on your application and business logic, here we simplify to a
            // generic function named promptForOtpCode which gives us the OTP code.
            String otpCode = promptForOtpCode();
            otpFinishStepCallback.onSuccess(new OtpFinishInput(otpCode));
        } catch (Exception e) {
            // if any issue with the OTP collection from the end user or the user wants to cancel
            // then call onError to exit the flow. In this example we simplify it as catching
            // an exception.
            otpFinishStepCallback.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

To use the Resend/Retry/Phone Change features, you need to install the iOS SDK version 6.5.1 or later.

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 callback.onSuccess(input: nil) to communicate to the SDK you have the customer’s agreement to deliver the SMS message.

Swift

class OtpStartStepNoPrompt: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

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

    // Implement this method to handle phone number collection for SMS OTP,
    // or to obtain user confirmation for initiating an SMS message.
    func execute(
        phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback
    ) {
        self.callback = callback
        // Since no phone number is needed, don't prompt the user.
        callback.onSuccess(input: nil)
    }
}

Call the callback.onError() 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.

Swift

class OtpFinishStepNoPrompt: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

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

    // Implement this method to collect the OTP value delivered via SMS.
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // Handle the OTP validation error if present.
        // Signal to UI components to display OtpFinishView
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
                // Signal to your UI components that the last provided OTP is invalid
                self.sheetObservable.isOtpValidationError = true
            } else {
                self.sheetObservable.isOtpValidationError = false
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Provide the collected OTP value to the SDK for validation.
    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)
    }

    // Notify the SDK of any issues encountered while obtaining the OTP value or if the user cancels the OTP flow.
    func handleOtpFinishError() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        callback.onError()
    }
}

Follow these instructions if implementing MobileAuth and collecting the phone number only if MobileAuth fails. This will implement OTP without allowing for SMS resends and phone number changes. If you do want those capabilities, please reference the subsequent tabs (Resend, Retry OTP, and Phone Number Change).In the start step, call the callback.onSuccess(input: otpStartInput) method to return the collected phone number to the SDK.

Swift

import Foundation
import ProveAuth
import SwiftUI

class OtpStartStepWithPrompt: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

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

    func execute(
        phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback
    ) {
        self.callback = callback
        if !phoneNumberNeeded {
            // If no phone number is needed, then don't prompt the user.
            callback.onSuccess(input: nil)
        } else {
            DispatchQueue.main.async {
                // If a phone number validation error is detected, ensure it is handled to provide feedback to the user.
                if case .phoneNumberValidationError = phoneValidationError {
                    print(
                        "found phoneValidationError: \(String(describing: phoneValidationError?.localizedDescription))"
                    )
                    // Update UI components to display OtpStartView with the phone number validation error.
                    self.sheetObservable.isPhoneValidationError = true
                } else {
                    self.sheetObservable.isPhoneValidationError = false
                }
                // Update UI components to display OtpStartView if a phone number is needed.
                self.sheetObservable.isOtpStartActive = true
            }
        }
    }

    // Return collected phone number to the SDK
    func handlePhoneNumber(phoneNumber: String) {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }

        let otpStartInput = OtpStartInput(phoneNumber: phoneNumber)
        // This is how you pass collected phone number to SDK
        callback.onSuccess(input: otpStartInput)
    }

    // Communicate any issues encountered while trying to obtain the phone number to the SDK.
    // 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()
    }
}

The finish step is implemented the same as the previous tab:

Swift

class OtpFinishStepNoPrompt: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

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

    // Implement this method to collect the OTP value delivered via SMS.
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // Handle the OTP validation error if present.
        // Signal to UI components to display OtpFinishView
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
                // Signal to your UI components that the last provided OTP is invalid
                self.sheetObservable.isOtpValidationError = true
            } else {
                self.sheetObservable.isOtpValidationError = false
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Provide the collected OTP value to the SDK for validation.
    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)
    }

    // Notify the SDK of any issues encountered while obtaining the OTP value or if the user cancels the OTP flow.
    func handleOtpFinishError() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        callback.onError()
    }
}

Swift

import Foundation
import ProveAuth
import SwiftUI

class OtpStartStepWithPrompt: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

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

    func execute(
        phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback
    ) {
        self.callback = callback
        if !phoneNumberNeeded {
            // If no phone number is needed, then don't prompt the user.
            callback.onSuccess(input: nil)
        } else {
            DispatchQueue.main.async {
                // If a phone number validation error is detected, ensure it is handled to provide feedback to the user.
                if case .phoneNumberValidationError = phoneValidationError {
                    print(
                        "found phoneValidationError: \(String(describing: phoneValidationError?.localizedDescription))"
                    )
                    // Update UI components to display OtpStartView with the phone number validation error.
                    self.sheetObservable.isPhoneValidationError = true
                } else {
                    self.sheetObservable.isPhoneValidationError = false
                }
                // Update UI components to display OtpStartView if a phone number is needed.
                self.sheetObservable.isOtpStartActive = true
            }
        }
    }

    // Return collected phone number to the SDK
    func handlePhoneNumber(phoneNumber: String) {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }

        let otpStartInput = OtpStartInput(phoneNumber: phoneNumber)
        // This is how you pass collected phone number to SDK
        callback.onSuccess(input: otpStartInput)
    }

    // Communicate any issues encountered while trying to obtain the phone number to the SDK.
    // 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()
    }
}

You can then send a new OTP SMS to the same phone number by implementing the finish step like this:

Swift

class OtpFinishStepMultipleResend: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

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

    // Implement this method to collect the OTP value delivered in the SMS message.
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // Handle the OTP validation error if present.
        // Update your UI to display the OtpFinishView
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
                // Update your UI to indicate that the provided OTP is invalid
                self.sheetObservable.isOtpValidationError = true
            } else {
                self.sheetObservable.isOtpValidationError = false
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

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

    // Communicate to the SDK any issues when host app trys to obtain the OTP value
    // or when users cancel the OTP flow
    func handleOtpFinishError() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        callback.onError()
    }

    // Call this method to request a new OTP code for the same mobile number.
    func sendNewOtp() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }
        callback.onOtpResend()
    }
}

Swift

import Foundation
import ProveAuth
import SwiftUI

class OtpStartStepWithPrompt: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

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

    func execute(
        phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback
    ) {
        self.callback = callback
        if !phoneNumberNeeded {
            // If no phone number is needed, then don't prompt the user.
            callback.onSuccess(input: nil)
        } else {
            DispatchQueue.main.async {
                // If a phone number validation error is detected, ensure it is handled to provide feedback to the user.
                if case .phoneNumberValidationError = phoneValidationError {
                    print(
                        "found phoneValidationError: \(String(describing: phoneValidationError?.localizedDescription))"
                    )
                    // Update UI components to display OtpStartView with the phone number validation error.
                    self.sheetObservable.isPhoneValidationError = true
                } else {
                    self.sheetObservable.isPhoneValidationError = false
                }
                // Update UI components to display OtpStartView if a phone number is needed.
                self.sheetObservable.isOtpStartActive = true
            }
        }
    }

    // Return collected phone number to the SDK
    func handlePhoneNumber(phoneNumber: String) {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }

        let otpStartInput = OtpStartInput(phoneNumber: phoneNumber)
        // This is how you pass collected phone number to SDK
        callback.onSuccess(input: otpStartInput)
    }

    // Communicate any issues encountered while trying to obtain the phone number to the SDK.
    // 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()
    }
}

Swift

class OtpFinishStepNoPrompt: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

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

    // Implement this method to collect the OTP value delivered via SMS.
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // Handle the OTP validation error if present.
        // Signal to UI components to display OtpFinishView
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
                // Signal to your UI components that the last provided OTP is invalid
                self.sheetObservable.isOtpValidationError = true
            } else {
                self.sheetObservable.isOtpValidationError = false
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Provide the collected OTP value to the SDK for validation.
    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)
    }

    // Notify the SDK of any issues encountered while obtaining the OTP value or if the user cancels the OTP flow.
    func handleOtpFinishError() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        callback.onError()
    }
}

Follow these instructions to allow the customer to re-enter their phone number. There is a max of three entries/send attempts.

Manual Request RequiredTo enable phone number change capabilities on your credentials, contact your Prove representative.

The start step is implemented the same as the previous tab:

Swift

import Foundation
import ProveAuth
import SwiftUI

class OtpStartStepWithPrompt: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

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

    func execute(
        phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback
    ) {
        self.callback = callback
        if !phoneNumberNeeded {
            // If no phone number is needed, then don't prompt the user.
            callback.onSuccess(input: nil)
        } else {
            DispatchQueue.main.async {
                // If a phone number validation error is detected, ensure it is handled to provide feedback to the user.
                if case .phoneNumberValidationError = phoneValidationError {
                    print(
                        "found phoneValidationError: \(String(describing: phoneValidationError?.localizedDescription))"
                    )
                    // Update UI components to display OtpStartView with the phone number validation error.
                    self.sheetObservable.isPhoneValidationError = true
                } else {
                    self.sheetObservable.isPhoneValidationError = false
                }
                // Update UI components to display OtpStartView if a phone number is needed.
                self.sheetObservable.isOtpStartActive = true
            }
        }
    }

    // Return collected phone number to the SDK
    func handlePhoneNumber(phoneNumber: String) {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }

        let otpStartInput = OtpStartInput(phoneNumber: phoneNumber)
        // This is how you pass collected phone number to SDK
        callback.onSuccess(input: otpStartInput)
    }

    // Communicate any issues encountered while trying to obtain the phone number to the SDK.
    // 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()
    }
}

You can prompt for a new phone number by implementing the finish step like this:

Swift

class OtpFinishStepWithPhoneChange: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

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

    // Implement this method to collect the OTP value delivered via SMS.
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // Handle the OTP validation error if present.
        // Update your UI to display the OTP finish view.
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
                // Update your UI to indicate that the provided OTP is invalid.
                self.sheetObservable.isOtpValidationError = true
            } else {
                self.sheetObservable.isOtpValidationError = false
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Return the collected 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)
    }

    // When callback.onMobileNumberChange() is evoked, OtpStartStep will be re-initiated
    // so that end-users can enter a different phone number via OtpStartStep.
    func handleMobileNumberChange() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set")
            return
        }
        callback.onMobileNumberChange()
    }
}

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, if provided in the /unify request. If this parameter was not provided, it will be blank in the response.
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.
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.

Only mobile channels are supported for this flow.

Initialize the Flow

You need to send a request to your back end server with the phone number, possessionType=none, and client request ID 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: "none",
  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.

Authenticate

Initialize the client-side SDK to place a Prove key on the device or to check if a Prove key is bound.

Web SDK

async function authenticate(isMobileWeb, authToken) {
  // Set up the authenticator for the mobile flow.
  let builder = new proveAuth.AuthenticatorBuilder();

  builder = builder
    .withAuthFinishStep((input) => verify(input.authId));
  
  const authenticator = builder.build();

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

Verify Mobile Number

In the AuthFinishStep of the client SDK, you’ll need to have the function make a call to an endpoint on your back end server. Your backend server should then call 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 possession_required if the reputation check 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, if provided in the /unify request. If this parameter was not provided, it will be blank in the response.
clientRequestId: a client-generated unique ID for a specific session. This field will be blank.
deviceId: the unique identifier for the Prove Key on the device. This field will be blank.
proveId: a unique ID to identify a specific customer obtained from a successful possession check. This field will be blank.

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

Perform Possession Check

If possession is required, your application needs to perform a customer-supplied possession check such as SMS OTP.

Call the Bind Endpoint

Call UnifyBind() after UnifyStatus() returns success=possession_required. Ensure your own possession check has succeeded. This binds the phone number to the Prove Key for future authentications.This function takes these required parameters:

correlationId: the ID returned by the Unify() function.
phoneNumber: the phone number to bind to the Prove Key.

rspUnifyBind, err := client.V3.V3UnifyBindRequest(context.TODO(), &components.V3UnifyBindRequest{
  CorrelationID: rspUnify.V3UnifyResponse.CorrelationID,
  PhoneNumber:   "2001004018",
})
if err != nil {
  return fmt.Errorf("error on UnifyBind(): %w", err)
}

The function returns the following fields:

success: true if the binding succeeded, false if it failed.
phoneNumber: the phone number that was bound to the Prove Key.
clientHumanId: a client-generated unique ID to identify a specific customer across business lines. This will be blank, unless provided in the /unify request.
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.
proveId: a unique ID to identify a specific customer obtained from a successful possession check.

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.

If you send a different phone number to /unify than the one registered to the Prove key, you will receive success=false when calling /unify-status. This is because the Prove Key is bound to a different number. Run the flow again with rebind=true in the /unify endpoint. This will force a full possession check and then, if valid, will rebind the Prove Key to the new phone number.

If you send a different phone number to /unify than the one registered to the Prove key, the customer will receive possession_required on the /unify-status call. You will need to call /unify-bind to rebind the Prove Key to the new number. Once it’s rebound, the previous number will ask for possession_required. The Prove key only supports one phone number.

Sandbox testing

Test users list

Follow the Testing Steps for expected behavior per step.

North America
International

Phone Number	First Name	Last Name
2001004014	Lorant	Nerger
2001004017	Jesse	Mashro

Phone Number	First Name	Last Name
+2001004025	Bertie	Fremont
+2001004028	Wendy	Strover

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.

Prompt Customer

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

Initiate Start Request

Your front end will send the phone number, possession type, final target URL, and client request ID 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.

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

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.

Follow the steps below to test the Prove Unified Authentication flow with Lorant Nerger on mobile. This user will fail Mobile Auth but pass OTP and return success=true in the /unify-status response. The user can then be sent through the Prove Unified Authentication flow again using the same phone number with a Prove key, bypassing possession.

Prompt Customer

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

Initiate Start Request

Your front end will send the phone number, possession type, and client request ID 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.

Send Auth Token to the Front End

Your back end will send the authToken to the front end. The front end will run OTP handling. You will see the following page. Enter 1234 to simulate a successful OTP.

Example of the OTP screen in the Prove Unified Authentication sandbox testing flow

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:

deviceId that’s an external identifier of the Prove ID.
proveId that is tied to this user.
success=true
phoneNumber that was initially passed.

You have a successful flow and a Prove key has been assigned to this phone number. Sending this user through again will bypass the possession check due to the Prove key. Send the user on through your authenticated flow.

Follow the steps below to test the Prove Unified Authentication flow with Lorant Nerger using customer-supplied possession. This user will pass the entire Unified Authentication flow using the customer’s possession and return success=true in the /unify-bind response. The user can then be sent through the Prove Unified Authentication flow again using the same phone number with a Prove key, bypassing possession.

Prompt Customer

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

Initiate Start Request

Verify Mobile Number

The back end then calls the /unify-status endpoint with the correlation ID to validate the phone number. The response provides:

success=possession_required since Prove is not performing the possession check.

Bind Prove Key

The back end will then call the /unify-bind endpoint with the correlation ID. The response provides:

proveId that is tied to this user.
success=true
phoneNumber that was initially passed.

Prove Possession - Desktop
Prove Possession - Mobile
Customer-Supplied Possession

Follow the steps below to test the Prove Unified Authentication flow with Jesse Mashiro on desktop. This user will fail the Unified Authentication flow using Prove’s possession and return success=false in the /unify-status response.

Prompt Customer

Start the onboarding flow on the initial screen and enter the phone number for Jesse Mashru.

Initiate Start Request

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. This user fails Instant Link.

Fail Possession Check

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:

success=false
phoneNumber that was initially passed.

The test user failed. Send the user through your exception process.

Follow the steps below to test the Prove Unified Authentication flow with Jesse Mashro on mobile. This user will pass Mobile Auth and return success=true in the /unify-status response. The user can then be sent through the Prove Unified Authentication flow again using the same phone number with a Prove key, bypassing possession.

Prompt Customer

Start the onboarding flow on the initial screen and enter the phone number for Jesse Mashro.

Initiate Start Request

Send Auth Token to the Front End

Your back end will send the authToken to the front end. The front end will fail Mobile Auth and OTP without prompting.

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:

success=false
phoneNumber that was initially passed.

The test user failed. Send the user through your exception process.

Follow the steps below to test the Prove Unified Authentication flow with Jesse Mashro using customer-supplied possession. This user will encounter a server error in the /unify-bind response, simulating an error when creating the Prove key.

Prompt Customer

Start the onboarding flow on the initial screen and enter the phone number for Jesse Mashro.

Initiate Start Request

Your front end will send the phone number and possession type 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.

Verify Mobile Number

The back end then calls the /unify-status endpoint with the correlation ID to validate the phone number. The response provides:

correlationId that’s tied to this flow.
success=possession_required since Prove is not performing the possession check.
phoneNumber that was initially passed.

Bind Prove Key

The back end will then call the /unify-bind endpoint with the correlation ID and phone number. You will receive a server error in the response.

Response

{
  "code": 8000,
  "message": "error at prove, try again later"
} 

The user has failed to generate a Prove key. Send the user through your exception process.

Prove Possession - Desktop
Prove Possession - Mobile
Customer-Supplied Possession

Follow the steps below to test the Prove Unified Authentication flow with Bertie Fermont on desktop. This user will pass the entire Unified Authentication flow using Prove’s possession and return success=true in the /unify-status response.

Prompt Customer

Start the onboarding flow on the initial screen and enter the phone number for Bertie Fremont.

Initiate Start Request

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. You will see the following page.

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 Prove key is placed as the Prove key only applies to mobile devices. Send the user on through your authenticated flow.

Follow the steps below to test the Prove Unified Authentication flow with Bertie Fromont on mobile. This user will fail Mobile Auth but pass OTP and return success=true in the /unify-status response. The user can then be sent through the Prove Unified Authentication flow again using the same phone number with a Prove key, bypassing possession.

Prompt Customer

Start the onboarding flow on the initial screen and enter the phone number for Bertie Fromont.

Initiate Start Request

Send Auth Token to the Front End

Your back end will send the authToken to the front end. The front end will run OTP handling. You will see the following page. Enter 1234 to simulate a successful OTP.

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:

deviceId that’s an external identifier of the Prove ID.
proveId that is tied to this user.
success=true
phoneNumber that was initially passed.

You have a successful flow and a Prove key has been assigned to this phone number. Send the user on through your authenticated flow.

Follow the steps below to test the Prove Unified Authentication flow with Bertie Fromont using customer-supplied possession. This user will pass the entire Unified Authentication flow using the customer’s possession and return success=true in the /unify-bind response. The user can then be sent through the Prove Unified Authentication flow again using the same phone number with a Prove key, bypassing possession.

Prompt Customer

Start the onboarding flow on the initial screen and enter the phone number for Bertie Fromont.

Initiate Start Request

Verify Mobile Number

The back end then calls the /unify-status endpoint with the correlation ID to validate the phone number. The response provides:

correlationId that’s tied to this flow.
success=possession_required since Prove is not performing the possession check.
phoneNumber that was initially passed.

Bind Prove Key

The back end will then call the /unify-bind endpoint with the correlation ID and phone number. The response provides:

correlationId that’s tied to this flow.
success=true
phoneNumber that was initially passed.

You have a successful flow and a Prove key has been assigned to this phone number. Send the user on through your authenticated flow.

Prove Possession - Desktop
Prove Possession - Mobile
Customer-Supplied Possession

Follow the steps below to test the Prove Unified Authentication flow with Wendy Stover on desktop. This user will fail the Unified Authentication flow using Proof’s possession and return success=false in the /unify-status response.

Prompt Customer

Start the onboarding flow on the initial screen and enter the phone number for Wendy Strover.

Initiate Start Request

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. You will see the following page.

Fail Possession Check

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:

correlationId that is tied to this flow.
success=false
phoneNumber that was initially passed.

The test user failed. Send the user through your exception process.

Follow the steps below to test the Prove Unified Authentication flow with Wendy Strover on mobile. This user will pass Mobile Auth and return success=true in the /unify-status response. The user can then be sent through the Prove Unified Authentication flow again using the same phone number with a Prove key, bypassing possession.

Prompt Customer

Start the onboarding flow on the initial screen and enter the phone number for Wendie Strover.

Initiate Start Request

Send Auth Token to the Front End

Your back end will send the authToken to the front end. The front end will perform a successful Mobile Auth.

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:

correlationId that is tied to this flow.
success=true
phoneNumber that was initially passed.

You have a successful flow and a Prove key has been assigned to this phone number. Send the user on through your authenticated flow.

Follow the steps below to test the Prove Unified Authentication flow with Wendie Strover using customer-supplied possession. This user will encounter a server error in the /unify-bind response, simulating an error when creating the Prove key.

Prompt Customer

Start the onboarding flow on the initial screen and enter the phone number for Wendie Strover.

Initiate Start Request

Verify Mobile Number

The back end then calls the /unify-status endpoint with the correlation ID to validate the phone number. The response provides:

correlationId that is tied to this flow.
success=possession_required since Prove is not performing the possession check.
phoneNumber that was initially passed.

Bind Prove Key

The back end will then call the /unify-bind endpoint with the correlation ID and phone number. You will receive a server error in the response.

Response

{
  "code": 8000,
  "message": "error at prove, try again later"
} 

The user has failed to generate a Prove key. Send the user through your exception process.

Get Started

Welcome

Know

Grow

Pre-Fill

Identity

Resources

Authentication Overview

How to implement

Configure OTP

Configure Instant Link

Configure OTP

Configure OTP

Sandbox testing

Test users list

Testing steps

Get Started

Welcome

Know

Grow

Pre-Fill

Identity

Resources

​How to implement

​Configure OTP

​Configure Instant Link

​Configure OTP

​Configure OTP

​Sandbox testing

​Test users list

​Testing steps

How to implement

Configure OTP

Configure Instant Link

Configure OTP

Configure OTP

Sandbox testing

Test users list

Testing steps