Server-Side SDK Guide

Use this guide when your backend must run the Prove Pre-Fill v3 sequence Start → Validate → Challenge → Complete with a Prove server SDK (Go, Java, .NET, TypeScript, or JavaScript). The same SDK methods apply to Prove Identity; where behavior differs, it is called out in the Challenge() section. For raw HTTP instead of snippets, use the reference links in the table below.

Prerequisites

Server SDK — Installed in your service (see Set up Prove SDKs in your project or Install the server SDK below).
OAuth credentials — Sandbox (or Production) client ID and secret from the Developer Portal; see Get started with Prove API authentication and Secure API credentials.
Client possession path — Your app runs the client SDK for Mobile Auth / OTP / Instant Link as required; see Prove Pre-Fill implementation guide and Prove Pre-Fill flow.

Operation	HTTP reference
Start	`POST /v3/start`
Validate	`POST /v3/validate`
Challenge	`POST /v3/challenge`
Complete	`POST /v3/complete`

Install the server SDK

Add the dependency for your language. The CodeGroup tabs show install commands and import lines.

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

Configure OAuth for the SDK

Initialize the client with your OAuth 2.0 client ID and client secret (environment variables or your secrets store).

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 expiration — Access tokens expire after 60 minutes. Refresh or obtain a new token before long-running jobs.

Follow the `Next` field

Each SDK call returns a Next map. Do not hard-code the full sequence after Start: read Next and call the indicated operation until the flow ends. The sections below describe parameters and return fields for each call.

`Start()`

Expose a server endpoint (for example POST /initiate) so your front end can send flow type, phone number, and any challenge inputs. On the server, call Start() with at least:

Flow type — desktop or mobile for the device class starting the session.

Possession channels — On desktop, possession typically uses Instant Link; on mobile, Mobile Auth then OTP when applicable. Instant Link and OTP sessions have short SMS-side timeouts; for behavior and UX, see Prove Pre-Fill flow.

Final target URL — Required when flowType=desktop: URL the customer reaches after tapping the Instant Link (max 128 characters).

Optional on Start() (or later on Challenge()):

ssn — Full SSN or last four digits.
dob — YYYY-MM-DD, YYYY-MM, or MM-DD.
allowOTPRetry — true to allow up to three OTP retries (defaults to false). Requires matching client SDK handling; see Prove Pre-Fill implementation guide — OTP.

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

Returns

Auth token — Short-lived JWT for the client Authenticate() call and possession.
Correlation ID — Store in server session; pass into Validate(), Challenge(), and Complete() for this flow. Session tied to this ID expires 15 minutes after Start() returns. Helps troubleshooting.
Next — Map of the next server operation to invoke.

Return the auth token (and any front-end payload you use) to the client after Start().

In Sandbox, include a test user phone number so the correct scenario runs. Omitting a valid persona can yield no test user found matching the phone number.

`Validate()`

After possession completes on the device, the client calls your backend (for example POST /verify). Then call Validate() with:

Correlation ID — From Start().

rspValidate, err := client.V3.V3ValidateRequest(ctx, &components.V3ValidateRequest{
	CorrelationID: rspStart.V3StartResponse.CorrelationID,
})
if err != nil {
	t.Fatal(err)
}

Returns

success — Whether mobile validation succeeded.
challengeMissing — When true, collect SSN or DOB (or call Challenge() if those values were already supplied on Start() per your flow).
phoneNumber — Validated number when present.
Next — Next operation.

Use challengeMissing and Next to decide whether to return a challenge UI to the browser or invoke Challenge() on the server.

`Challenge()`

When Validate() includes v3-challenge in Next, call Challenge() to retrieve attributes for the phone number plus challenge. Pre-Fill uses this path. Prove Identity may move to v3-complete in Next after a successful Validate() instead of v3-challenge. Parameters

Correlation ID — From Start() (required).

If Validate() set challengeMissing=true, include one of:

ssn
dob — Same formats as on Start().

rspChallenge, err := client.V3.V3ChallengeRequest(ctx, &components.V3ChallengeRequest{
	CorrelationID: rspStart.V3StartResponse.CorrelationID,
	Ssn:           provesdkservergo.String("565228370"),
})
if err != nil {
	t.Fatal(err)
}

Returns

success — Whether customer data was returned.
individual — Attribute map (up to three addresses possible).
Next — Next operation.

When success is true, return individual to the client for pre-fill.

`Complete()`

After the customer confirms or edits pre-filled data, submit the payload to your server and call Complete() — the final verification step. Parameters

Correlation ID — From Start(); must match UUID pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$.
individual — The customer data map to verify.

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

Returns

success — Whether verification succeeded.
Next — Typically Done when the flow is finished.

Respond to the client with the verification outcome.

Get Started

Welcome

Resources

Server-Side SDK Guide

Prerequisites

Install the server SDK

Configure OAuth for the SDK

Follow the `Next` field

`Start()`

`Validate()`

`Challenge()`

`Complete()`

Get Started

Welcome

Resources

​Prerequisites

​Install the server SDK

​Configure OAuth for the SDK

​Follow the Next field

​Start()

​Validate()

​Challenge()

​Complete()

Prerequisites

Install the server SDK

Configure OAuth for the SDK

Follow the `Next` field

`Start()`

`Validate()`

`Challenge()`

`Complete()`