Prove Verified Users℠ SDK Guide

​

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

To view API endpoint code samples in 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 configure your OAuth client ID and client secret.

You can use 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),
  }),
)

When you test in the European Union, set proveEnv to uat-eu.

​

Verify()

Add an endpoint to your server such as POST /verify so the front end can submit the flow type, phone number, first name, and last name. On the back end, you’ll start a Prove flow with a call to the Verify() 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.
• Phone Number: phone number of the customer.

• First Name: first name of the customer.
• Last Name: last name of the customer.

• 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.

The following are optional parameters:

• SMS Message: a field to customize the message body sent in the Instant Link or OTP SMS message. Otherwise, you can use Prove defaults.
• Client Customer ID: 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.
• Client Request ID: a client-generated unique ID for a specific session. You can identify specific requests using this field. You determine the format of this ID.

// Send the verify request.
rspVerify, err := client.V3.V3VerifyRequest(ctx, &components.V3VerifyRequest{
  FirstName:      "Addy",
  LastName:       "Epinay",
  PhoneNumber:    "2001004010",
  PossessionType: "desktop",
  FinalTargetURL: provesdkservergo.String("https://www.example.com"),
})
if err != nil {
  t.Fatal(err)
}

The function returns the following fields:

• Auth Token: send this to your client-side code to pass into 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 also aids in troubleshooting. The session expires in 15 minutes from when the correlation ID returns from the Start() call.

• Success: true if the challenge succeeded and customer info returned, false if it failed, or pending if the possession check needs to complete first.

• Possession Result: either success if the possession check was successful, failed if it failed, or pending if the possession check needs to complete first.

• Verify Result: either success if the verification was successful, failed if it failed, or pending if the verification check needs to complete first.

If using possession, then the response has the authToken, returned to the front end.

​

VerifyStatus()

Once the possession check is complete, your back end calls VerifyStatus() to get the final result in the success field.

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

This function takes this required parameter:

• Correlation ID: the ID returned by the Verify() 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}$.

rspVerifyStatus, err := client.V3.V3VerifyStatusRequest(context.TODO(), &components.V3VerifyStatusRequest{
	CorrelationID: rspVerify.V3VerifyStatusRequest.CorrelationID,
})
if err != nil {
	return fmt.Errorf("error on VerifyStatus(): %w", err)
}