Skip to main content
Prove provides server-side SDKs in the following languages: Go, Java, .NET, 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.

​
Authentication

To access the Prove API, use your OAuth 2.0 client ID and client secret. You can load these from environment variables or another method: 
clientID := os.Getenv("PROVE_CLIENT_ID")
clientSecret := os.Getenv("PROVE_CLIENT_SECRET")

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

client := provesdkservergo.New(
	provesdkservergo.WithServer(proveEnv),
	provesdkservergo.WithSecurity(components.Security{
		ClientID:     provesdkservergo.String(clientID),
		ClientSecret: provesdkservergo.String(clientSecret),
	}),
)
Token ExpirationThe OAuth token expires after 60 minutes, requiring you to get another token.

​
Next field

Each of the functions return a Next field. This field signals which function you 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, 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.
Possession TimeoutsWhen flow type is desktop, Instant Link performs the possession check. When flow type is mobile, first Mobile Auth, if enabled, and then one-time password (OTP) as a fallback. The Instant Link session has a three minute timeout from when it’s sent through SMS to when the customer can selects it. The OTP session has a two minute timeout from when it’s sent through SMS to when the customer can enter in the OTP.
  • Final Target URL: required when flowType=desktop. This should be a URL you support. When the customer clicks the Instant Link, the workflow sends the customer to this URL, which instructs them to continue the process. Maximum length is 128 characters.
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().
  • allowOTPRetry: set to true to allow the customer to re-enter the OTP up to three times. Defaults to false.
    For OTP retries, make sure to implement client SDK changes as detailed in the Implementation Guide.
ctx := context.TODO()

rspStart, err := client.V3.V3StartRequest(ctx, &components.V3StartRequest{
	FlowType:       "desktop",
	FinalTargetURL: provesdkservergo.String("https://prove.com"),
	PhoneNumber:    provesdkservergo.String("2001001686"),
	Ssn:            provesdkservergo.String("8370"),
})
if err != nil {
	t.Fatal(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 make.
Return the auth token in a response to the front end.
The phone number field is also required in Sandbox to determine which scenario you’re testing. Neglecting to pass in the phone number of a valid test user returns a “no test user found matching the phone number” error.

​
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(ctx, &components.V3ValidateRequest{
	CorrelationID: rspStart.V3StartResponse.CorrelationID,
})
if err != nil {
	t.Fatal(err)
}
The function returns the following fields:
  • Success: either true if the mobile number validation was successful, or false if it failed.
  • Challenge Missing: when true, pass the challenge into the Challenge() function.
  • Phone Number: either the validated phone number or no field.
  • Next: map of the next API call.
The challenge missing field determines if you must 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. 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(ctx, &components.V3ChallengeRequest{
	CorrelationID: rspStart.V3StartResponse.CorrelationID,
	Ssn:           provesdkservergo.String("565228370"),
})
if err != nil {
	t.Fatal(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 call.
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 regular expression: ^[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(ctx, &components.V3CompleteRequest{
	CorrelationID: rspStart.V3StartResponse.CorrelationID,
	Individual: components.V3CompleteIndividualRequest{
		FirstName: provesdkservergo.String("Tod"),
		LastName:  provesdkservergo.String("Weedall"),
		Addresses: []components.V3CompleteAddressEntryRequest{
			{
				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{
			"tweedalld@ehow.com",
		},
	},
})
if err != nil {
	t.Fatal(err)
}
The function returns the following fields:
  • Success: true if customer information returned.
  • Next: map of the next API call you need to make, in this case, Done.
You can then respond to the front end with the results of the customer verification.
SDK UpdatesProve hosts the server-side SDKs on GitHub. Once you create a free GitHub account, you can Watch any of the projects to receive notifications.
⌘I