Server-Side SDK Guide

Prove provides server-side SDKs in the following languages: Go, Java, TypeScript, and JavaScript. If you use a different back end language, you can interact with the API endpoints.

​

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 select your language from the tabs.

​

OAuth for Authentication

To access the Prove API, you’ll need to use your OAuth client ID and client secret.

You can load these from environment variables or another method:

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

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

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

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

​

Next Field

Each of the functions return a Next field. This field signals which function you need to call next.

​

Start()

Add an endpoint to your server such as POST /initiate so the front end can submit the flow type, phone number, and the challenge. On the back end, 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 customer is starting their flow on.

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

These parameters are optional:

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

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

// Send the start request.
rspStart, err := client.V3.V3StartRequest(context.TODO(), &components.V3StartRequest{
  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 through the Authenticate() function - it’s a short lived JSON Web Token (JWT) tied to the current flow and used for the possession checks.

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

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

Return the auth token in a response to the front end.

​

Validate()

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

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

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

The function returns the following fields:

• Success: 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 front end and request either the last four of their social security number or date of birth. If the challenge was already passed into the Start() call, the back end can then make a call to the Challenge() function and return the results to the front end.

​

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 customer information matching the mobile number and challenge. The Challenge() capability is available in Prove Pre-Fill. You’ll notice that when using Prove Identity, if Validate() is successful, it returns v3-complete as one of the keys in the Next field map instead of v3-challenge.

This function takes has one required parameter:

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

If the Validate() function returned Challenge Missing=true, send one of these parameters in the request:

• ssn: full or last four digits of the customer’s social security number.

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

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 customer info returned.

• Individual: customer information in a map.

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

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

​

Complete()

Once the customer reviews their information and makes any edits, submit the customer information to the back end for verification.

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

This function takes these required parameters:

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

• Individual: customer information in a map.

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