Prove Unify 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.

​

Unify()

Add an endpoint to your server such as POST /unify so the front end can submit the possession type and phone number. On the back end, you’ll start a Prove Unify flow with a call to the Unify() function. This function takes these required parameters:

• Possession Type: specify mobile, desktop, or none (for Customer-supplied possession) to describe which type of device the end user is starting their flow on.
• Phone Number: phone number of the end user.

Additional parameters:

• Final Target URL: required when possessionType=desktop. It can be either a Prove provided URL or your own URL that instructs the end user to close their mobile browser.
• SMS Message: optional 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.
• Email: optional customer identifier.
• IP Address: optional customer identifier.

// Send the Unify request.
rspUnify, err := client.V3.V3UnifyRequest(ctx, &components.V3UnifyRequest{
  PhoneNumber:    "2001004014",
  PossessionType: "mobile",
  ClientRequestID: provesdkservergo.String("client-abc-123"),
})
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 the UnifyStatus() function call 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 Unify() call.

• Success: will return pending for this initial call.

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

​

UnifyStatus()

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

This function takes this required parameter:

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

rspUnifyStatus, err := client.V3.V3UnifyStatusRequest(context.TODO(), &components.V3UnifyStatusRequest{
	CorrelationID: rspUnify.V3UnifyResponse.CorrelationID,
})
if err != nil {
	return fmt.Errorf("error on UnifyStatus(): %w", err)
}

​

UnifyBind()

For customer-supplied possession flows only, you’ll need to call UnifyBind() after your own possession check has succeeded. This binds the phone number to the Prove Key for future authentications.

This function takes these required parameters:

• Correlation ID: the ID returned by the Unify() function.
• Phone Number: the phone number to bind to the Prove Key.

rspUnifyBind, err := client.V3.V3UnifyBindRequest(context.TODO(), &components.V3UnifyBindRequest{
	CorrelationID: rspUnify.V3UnifyResponse.CorrelationID,
  PhoneNumber:   "2001004018",
})
if err != nil {
	return fmt.Errorf("error on UnifyBind(): %w", err)
}