Prove Pre-Fill® and Prove Identity℠ SDK Guide

Prove provides server-side SDKs in the following languages: Java, TypeScript/JavaScript, and Go. If you use a different backend language, you can easily interact with the REST APIs.

​

Installation

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

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

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

Prove provides code samples for how to interact with the API endpoints in many different languages. Browse the API Reference page and click your language from the top tabs.

​

OAuth for Authentication

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

You can load them from environment variables or another method:

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

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

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

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

​

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.

​

Start()

Add an endpoint to your server (example: POST /initiate) so the frontend/client code can submit the flow type, phone number, and challenge (either last four of SSN or date of birth). On the backend, you’ll start a 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, pass one of these parameters:

• ssn: full or last four digits of the end user’s social security number. You can pass it into Start() or Challenge().

• dob: date of birth in one of these formats: YYYY-MM-DD, YYYY-MM, MM-DD. You can pass it into Start() or Challenge().

Here is an example:

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

The function returns the following fields:

• Auth Token: send this to your client-side code via the Authenticate() function - it’s a short lived JSON Web Token (JWT) tied to the current flow and used to facilitate the possession checks.

• Correlation ID: save this in your current session, you will pass it in to each of the Validate(), Challenge(), and Complete() function calls of the same flow. The correlation ID allows Prove to tie together different system calls for the same Prove flow. It can aids in troubleshooting. The session will expire in 15 minutes from when the correlation ID returns from the Start() call.

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

Return the auth token in a response to the frontend.

​

Validate()

Once the possession checks finish on the mobile device, the finish handler on the client SDK will execute, making a request to your server (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:

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

The function returns the following fields:

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

• Challenge Missing: true if you need to pass the challenge into the Challenge() function.

• 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 four 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, call the Challenge() function 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 four 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:

rspChallenge, err := client.V3.V3ChallengeRequest(context.TODO(), &components.V3ChallengeRequest{
	CorrelationID: rspStart.V3StartResponse.CorrelationID,
	Dob:           provesdkservergo.String("1980-03-15"),
})
if err != nil {
    return fmt.Errorf("error on Challenge(): %w", err)
}

The function returns the following fields:

• Success: true if user info returned.

• 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, 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 (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:

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