Prove® Platform Server-Side SDK Guide

We provide server SDKs in the following languages: Java, TypeScript/JavaScript, and Go. If your backend language is not currently supported, you can easily interact with our REST APIs.

​

Installation

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

​

OAuth for Authentication

In order to access the Prove API, you’ll need to provide your OAuth client ID and client secret. We recommend storing them.

To access the Sandbox environment, use server environment uat-us. To access the production environment, use server environment prod-us. You can see the code samples below.

You can load them from environment variables or another method:

​

Next Field

Each of the functions return a Next field. This field is a map that tells you which function you need to call next, or in the case of done, no further calls are needed. These are the possible return values:

• v3-validate: /v3/validate

• v3-challenge: /v3/challenge

• v3-complete: /v3/complete

• done: done

​

Start()

To start the implementation, add a new endpoint to your server (example: POST /initiate) so the frontend/client code can submit the flow type, phone number, and challenge (either last 4 of SSN or date of birth). On the backend, you’ll start a new Prove flow with a call to the Start() function. This function takes these required parameters:

• Flow Type: either desktop or mobile to describe which type of device the end user is starting their flow on.

• Final Target URL: only required when Flow Type=desktop. It can be either a Prove provided URL or your own URL that instructs the end user to close their mobile browser.

Optionally, one of these parameters can be passed in:

• SSN: full or last 4 digits of the end user’s social security number. If passed into Start(), then it does not need to be passed into Challenge().

• DOB: date of birth in one of these formats: YYYY-MM-DD, YYYY-MM, MM-DD. If passed into Start(), then it does not need to be passed into Challenge().

Here is an example:

The function returns the following fields:

• Auth Token: send this to your client side code so it can be passed into the Authenticate() function - it’s a short lived JWT (authentication token) that is tied to the current flow and used to facilitate the possession checks.

• Correlation ID: save GUID in your current session, it will need to be passed in to each of the Validate(), Challenge(), and Complete() function calls of the same flow.

• Next: map of the next API you need to call you need to make.

You should then return the auth token in a response to the frontend.

​

Validate()

Once the possession checks are completed on the mobile device, the finish handler on the client SDK will be called and that should make a request to your server (you’ll need another new endpoint, for example: POST /verify) to make the next call in the flow to the Validate() function.

This function takes only this required parameter:

• Correlation ID: this is the ID returned by the Start() function.

Here is an example:

The function returns the following fields:

• Success: either true if the mobile number validation was successful, or false if it failed.

• Challenge Missing: either true if the challenge needs to be passed into the Challenge() function, or false if the challenge is not needed.

• Phone Number: either the validated phone number or no field.

• Next: map of the next API you need to call you need to make.

The challenge missing field determines if you need to return to the frontend and request an additional user input of either the last 4 of their social security number or date of birth. If the challenge was already passed into the Start() call (challengeMissing=false and next contains v3-challenge), the backend can then make a call to the Challenge() function and return the results to the frontend.

​

Challenge()

If the Validate() function returns v3-challenge as one of the keys in the Next field map, the Challenge() function may be called to return the user information matching the mobile number and challenge.

This function takes has one required parameter:

• Correlation ID: this is the ID returned by the Start() function.

If the Validate() function returned Challenge Missing=true, one of these parameters are also required:

• SSN: full or last 4 digits of the end user’s social security number.

• DOB: date of birth in one of these formats: YYYY-MM-DD, YYYY-MM, MM-DD.

Here is an example:

The function returns the following fields:

• Success: either true if the challenge was successful and user info is returned, or false if it failed.

• Individual: user information in a map.

• Next: map of the next API you need to call you need to make.

If the success field is true, you should return the user information in a response to the frontend to pre-fill the form.

​

Complete()

Once the end user reviews their information and makes any edits, they need to submit the user information to the backend (new endpoint example: POST /finish) for verification.

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

This function takes these required parameters:

• Correlation ID: this is the ID returned by the Start() function. It will validate against this RegEx: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$.

• Individual: user information in a map.

Here is an example: