Implementation Guide
Review the steps for implementing Prove Unify
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:
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.
- 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.
Prove manages a maven repository with Android binaries to enable integration with Gradle.
Update the dependencies object in the build.gradle
file:
You’ll also need to point to the repository by updating your settings.gradle
file with the Maven repository:
The following needs added to the build.gradle
file to also download dependency libraries:
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:
The Prove Auth SDK and its children SDKs merge the following permissions into the main application:
Prove manages a repository with the libraries to enable integration.
Execute the following to import CocoaPod from the Prove pod repository:
Implement Prove Unify
To integrate the Prove Unify solution, you must use the client-side SDK.
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
:
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
:
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 anad possession type to start the flow.
Additional parameters:
-
finalTargetURL
: required whenflowType=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. -
smsMessage
: optional field to customize the message body sent in the Instant Link or OTP SMS message. Otherwise, you can use Prove defaults. -
clientCustomerId
: a client-generated unique ID for a specific customer. You can link calls related to the same customer, across different requests or sessions. The client defines the format of this ID. -
clientRequestId
: a client-generated unique ID for a specific session. You can identify specific requests using this field. You determine the format of this ID.
The function returns the following fields:
-
authToken
: send this to your client-side code to pass into theAuthenticate()
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 theUnifyStatus()
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 theUnify()
call. -
success
: will returnpending
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.
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.
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.
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.
Call the resolve(input: InstantStartInput)
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 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.
wss: device.uat.proveapis.com
and wss: device.proveapis.com
.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.
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.
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.
Call the resolve(input: InstantStartInput)
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 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.
wss: device.uat.proveapis.com
and wss: device.proveapis.com
.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.
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.
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:
OtpFinishStep
example:
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.
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.
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:
OtpFinishStep
example:
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.
The function returns the following fields:
-
success
: eithertrue
if the mobile number validation was successful, orfalse
if it failed. -
phoneNumber
: the phone number associated with the possession check.
You can then respond to the front end with the results of the authentication.
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
:
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
:
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 anad possession type to start the flow.
Additional parameters:
-
finalTargetURL
: required whenflowType=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. -
smsMessage
: optional field to customize the message body sent in the Instant Link or OTP SMS message. Otherwise, you can use Prove defaults. -
clientCustomerId
: a client-generated unique ID for a specific customer. You can link calls related to the same customer, across different requests or sessions. The client defines the format of this ID. -
clientRequestId
: a client-generated unique ID for a specific session. You can identify specific requests using this field. You determine the format of this ID.
The function returns the following fields:
-
authToken
: send this to your client-side code to pass into theAuthenticate()
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 theUnifyStatus()
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 theUnify()
call. -
success
: will returnpending
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.
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.
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.
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.
Call the resolve(input: InstantStartInput)
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 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.
wss: device.uat.proveapis.com
and wss: device.proveapis.com
.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.
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.
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.
Call the resolve(input: InstantStartInput)
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 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.
wss: device.uat.proveapis.com
and wss: device.proveapis.com
.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.
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.
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:
OtpFinishStep
example:
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.
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.
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:
OtpFinishStep
example:
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.
The function returns the following fields:
-
success
: eithertrue
if the mobile number validation was successful, orfalse
if it failed. -
phoneNumber
: the phone number associated with the 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 and possessionType=none
to start the flow.
Additional parameters:
-
clientCustomerId
: a client-generated unique ID for a specific customer. You can link calls related to the same customer, across different requests or sessions. The client defines the format of this ID. -
clientRequestId
: a client-generated unique ID for a specific session. You can identify specific requests using this field. You determine the format of this ID.
The function returns the following fields:
-
authToken
: send this to your client-side code to pass into theAuthenticate()
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 theUnifyStatus()
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 theUnify()
call. -
success
: will returnpending
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.
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.
The function returns the following fields:
success
: eithertrue
if the mobile number validation was successful, orfalse
if it failed, orpossession_required
if customer-supplied possession flow requires additional steps.
If success=true
, the phone number is valid and you can proceed with your customer flow.
phoneNumber
: the phone number associated with the possession check.
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 theUnify()
function. -
phoneNumber
: the phone number to bind to the Prove Key.
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.
Test Your Prove Implementation
Next, reference the Sandbox test scenarios to test users and simulate different behaviors encountered in production.
To launch in Production, please contact your Prove representative.