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"
)
To view API endpoint code samples in different languages, browse the API Reference page and select your language.

​
Authentication

To access the Prove API, configure your OAuth 2.0 client ID and client secret. You can use 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),
	}),
)
When you test in the European Union, set proveEnv to uat-eu.
Token ExpirationThe OAuth token expires after 60 minutes. If it expires, generate another token.

​
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, start a Prove Unified Authentication 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.
In sandbox, the phone number field determines which scenario to test. If you forget to pass in the phone number of a valid test user, then it returns a “no test user found matching the phone number” error.
Possession TimeoutsWhen possession type is desktop, Instant Link executes the possession check. When possession type is mobile, first Prove Key is checked, then fallback to one-time password (OTP). The Instant Link session has a three minute timeout from when it’s sent through SMS to when the end user can select the link. The OTP session has a two minute timeout from when it’s sent through SMS to when the end user can enter in the OTP.
Optional parameters:
  • Final Target URL: required when possessionType=desktop. This should be a URL you support. Once the customer clicks the Instant Link, they’re redirected to this URL. It should instruct the customer to continue the workflow. Maximum length is 128 characters.
  • Check Reputation: if true, TrustScore verification will be performed.
  • Client Human ID: a client-generated unique ID to identify a specific customer across business lines.
  • 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 decide the format of this ID.
  • Device ID: the unique identifier for the Prove Key on the device.
  • Email: optional customer identifier.
  • IP Address: optional customer identifier.
  • proveId: a unique ID to identify a specific customer obtained from a previous successful authentication.
  • rebind: if true, rebinds the Prove Key with the newly verified phone number.
  • Allow OTP Retry: 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.
rspUnify, err := client.V3.V3UnifyRequest(ctx, &components.V3UnifyRequest{
	PossessionType: "desktop",
	FinalTargetURL: provesdkservergo.String("https://google.com"),
	PhoneNumber:    provesdkservergo.String("2001004014"),
})
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: returns 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 regular expression: ^[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(ctx, &components.V3UnifyStatusRequest{
	CorrelationID: &rspUnify.V3UnifyResponse.CorrelationID,
})
if err != nil {
	t.Fatal(err)
}
The function returns the following fields:
  • Success: true if the possession check succeeded, false if it failed, or possession_required if Customer-supplied possession flow requires additional steps.
  • Phone Number: the phone number associated with the possession check.
  • clientHumanId: a client-generated unique ID to identify a specific customer across business lines.
  • clientRequestId: a client-generated unique ID for a specific session. This can be used to identify specific requests.
  • deviceId: the unique identifier for the Prove Key on the device.
  • evaluation: the evaluation result for the Global Fraud Policy.
  • proveId: a unique ID to identify a specific customer obtained from a successful possession check.
You can then respond to the front end with the results of the authentication.

​
UnifyBind()

For customer-supplied possession flows only, 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)
}
The function returns the following fields:
  • Success: true if the binding succeeded, false if it failed.
  • Phone Number: the phone number that was bound to the Prove Key.
  • clientHumanId: a client-generated unique ID to identify a specific customer across business lines.
  • clientRequestId: a client-generated unique ID for a specific session. This can be used to identify specific requests.
  • deviceId: the unique identifier for the Prove Key on the device.
SDK UpdatesFind the server-side SDKs on GitHub. Once you create a free GitHub account, you can Watch any of the projects to receive notifications when there are updates.