Documentation Index
Fetch the complete documentation index at: https://developer.prove.com/llms.txt
Use this file to discover all available pages before exploring further.
Possession requires both a client-side SDK (Web, iOS, or Android) and these platform APIs:
Prerequisites
- Access token — Obtain a bearer token using Prove OAuth (Authentication). Use the same token for
POST /v3/unify, POST /v3/unify-status, and POST /v3/unify-bind.
- Server — Use a Prove server SDK or call those endpoints directly. Use the reference pages for full request bodies, optional fields, and responses.
- Client SDK — Install the Web, Android, or iOS SDK for possession checks and the Prove Key. For the browser flow, see Identity Web SDK.
Implementation steps
You must integrate the client-side SDK for possession checks and the Prove Key.
This section only applies to mobile channels.
Determine Type of Flow
Web SDK
Android SDK
iOS SDK
Decide if the customer is on a mobile or desktop browser using this example. If the isMobile is true, set mobile as the flowType for the Start() function on the server, otherwise you can set desktop:// Check if the customer is on a mobile or desktop browser.
const authCheck = new proveAuth.AuthenticatorBuilder().build();
let isMobile = authCheck.isMobileWeb()
When using the Android SDK, set mobile as the flowType for the Start() function on the server.
When using the iOS SDK, set mobile as the flowType for the Start() function on the server.
Initialize the Flow
Send a request to your back end server with possessionType=none to start the flow. See POST /v3/unify for optional identifiers such as clientCustomerId and clientRequestId and the full response.// Send the Unify request.
rspUnify, err := client.V3.V3UnifyRequest(ctx, &components.V3UnifyRequest{
PossessionType: "none",
ClientRequestID: provesdkservergo.String("client-abc-123"),
})
if err != nil {
t.Fatal(err)
}
Return the authToken to the client for Authenticate(). Persist correlationId for UnifyStatus(). See POST /v3/unify for all response fields, JWT behavior, and session timing. Authenticate
Once you have the authToken, build the authenticator for both the mobile and desktop flows. Web SDK
Android SDK
iOS SDK
async function authenticate(isMobileWeb, authToken) {
// Set up the authenticator for either mobile or desktop flow.
let builder = new proveAuth.AuthenticatorBuilder();
if (isMobileWeb) {
// Set up Mobile Auth and OTP.
builder = builder
.withAuthFinishStep((input) => verify(input.authId))
// If support for AT&T carrier is required, pixel mode should be selected via
// .withMobileAuthImplementation("pixel")
// otherwise, "fetch" mode should be preferred by default
.withMobileAuthImplementation("fetch")
.withOtpFallback(otpStart, otpFinish);
} else {
// Set up Instant Link.
builder = builder
.withAuthFinishStep((input) => verify(input.authId))
.withInstantLinkFallback(instantLink)
.withRole("secondary");
}
const authenticator = builder.build();
// Authenticate with the authToken.
return authenticator.authenticate(authToken);
}
// Object implementing AuthFinishStep interface
AuthFinishStep authFinishStep = new AuthFinishStep() {
...
};
// Objects implementing OtpStartStep/OtpFinishStep interfaces
OtpStartStep otpStartStep = new OtpStartStep() {
...
};
OtpFinishStep otpFinishStep = new OtpFinishStep() {
...
};
ProveAuth proveAuth = ProveAuth.builder()
.withAuthFinishStep(authId -> verify(authId)) // verify(authId) call defined in #Validate the Mobile Phone section
.withOtpFallback(otpStartStep, otpFinishStep)
.withContext(this)
.build();
The mobile data connection can sometimes be unavailable during testing. The Builder class offers a withTestMode(boolean testMode) method, which permits simulated successful session results while connected to a Wi-Fi network only. Testing using a Wi-Fi connection is useful in the Sandbox environment.ProveAuth proveAuth = ProveAuth.builder()
.withAuthFinishStep(authId -> verify(authId))
.withOtpFallback(otpStartStep, otpFinishStep)
.withContext(this)
.withTestMode(true) // Test mode flag
.build();
The ProveAuth object is thread safe. You can use it as a singleton. Most Prove Auth methods are blocking and therefore can’t execute in the main app thread. The app employs an executor service with a minimum of two threads to manage threads due to the ability to process concurrent blocking requests.public class MyAuthenticator {
private final MyBackendClient backend = new MyBackendClient(); // Backend API client
private final AuthFinishStep authFinishStep = new AuthFinishStep() {
@Override
void execute(String authId) {
try {
AuthFinishResponse response = backend.authFinish("My App", authId);
... // Check the authentication status returned in the response
} catch (IOException e) {
String failureCause = e.getCause() != null ? e.getCause().getMessage() : "Failed to request authentication results";
// Authentication failed due to request failure
}
}
};
private ProveAuth proveAuth;
public MyAuthenticator(Context context) {
proveAuth = ProveAuth.builder()
.withAuthFinishStep(authFinishStep)
.withOtpFallback(otpStartStep, otpFinishStep)
.withContext(context)
.build();
}
public void authenticate() throws IOException, ProveAuthException {
AuthStartResponse response = backend.authStart("My Prove Auth App");
proveAuth.authenticate(response.getAuthToken());
}
}
// Object implementing ProveAuthFinishStep protocols
let finishStep = FinishAuthStep()
// Objects implementing OtpStartStep/OtpFinishStep protocols
let otpStartStep = MobileOtpStartStep()
let otpFinishStep = MobileOtpFinishStep()
let proveAuthSdk: ProveAuth
proveAuthSdk = ProveAuth.builder(authFinish: finishStep)
.withOtpFallback(otpStart: otpStartStep, otpFinish: otpFinishStep)
.build()
If a mobile data connection is unavailable during testing, use the Builder class. It permits simulated successful session results while connected to a Wi-Fi network. Testing using a Wi-Fi connection is useful in the Sandbox environment.proveAuthSdk = ProveAuth.builder(authFinish: finishStep)
.withMobileAuthTestMode() // Test mode flag
.build()
The Prove Auth object is thread safe and used as a singleton. Most Prove Auth methods are blocking and therefore can’t execute in the main app thread. The app employs an executor service with a minimum of two threads to manage threads due to the SDK’s ability to process concurrent blocking requests.// authToken retrieved from your server via StartAuthRequest
proveAuthSdk.authenticate(authToken) { error in
DispatchQueue.main.async {
self.messages.finalResultMessage = "ProveAuth.authenticate returned error: \(error.localizedDescription)"
print(self.messages.finalResultMessage)
}
}
Verify Mobile Number
In the AuthFinishStep, specify a function to call once the possession checks complete on the mobile phone. This endpoint on your back end server calls the UnifyStatus() function to validate the phone number. The AuthFinishStep then completes.rspUnifyStatus, err := client.V3.V3UnifyStatusRequest(context.TODO(), &components.V3UnifyStatusRequest{
CorrelationID: rspUnify.V3UnifyResponse.CorrelationID,
})
if err != nil {
return fmt.Errorf("error on UnifyStatus(): %w", err)
}
Use success (including possession_required when a possession check is still required) to drive your UI and next server calls. See POST /v3/unify-status for the full response schema. Interpret evaluation using the Global Fraud Policy. Perform Possession Check
If success returned possession_required, your app must perform a customer-supplied possession check such as SMS OTP. Only proceed to the next step if the possession check passes.
Call the Bind Endpoint
Call UnifyBind() after UnifyStatus() returns success=possession_required. Call this endpoint if and only if the possession check has passed. This binds the phone number to the Prove Key for future authentications.This function requires correlationId and phoneNumber. See the /v3/unify-bind reference for the full schema. You can also send optional fields such as clientRequestId for session tracking.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)
}
Return the binding outcome to the client. See POST /v3/unify-bind for all response fields. Interpret evaluation using the Global Fraud Policy.If you send a different phone number to /unify than the one registered to the Prove key, the customer receives possession_required on the /unify-status call. Call /unify-bind to rebind the Prove Key to the new number. Once it’s rebound, the first number responds with possession_required. The Prove key only supports one phone number.
Sandbox Testing
Prerequisites
Test users list
Short-term test users
Use this test user when performing initial testing with cURL or Postman. This test user skips the client-side SDK authentication to walk you through the sequence of API calls.
North America
International
| Phone Number | First Name | Last Name |
|---|
| 2001004018 | Barbaraanne | Canet |
| Phone Number | First Name | Last Name |
|---|
| +2001004029 | Janos | Martina |
After initial short-term testing, implement the client-side SDK and use the remaining test users to test your implementation.
Mobile Auth test users
Follow the Testing Steps for expected behavior per step. These users allow you to test “Prove Possession” and “Prove Passive Authentication with Customer-Supplied Possession Fallback” flows.
North America
International
| Phone Number | First Name | Last Name |
|---|
| 2001004016 | Inge | Galier |
| 2001004017 | Jesse | Mashro |
| 2001004041 | Penny | Jowers |
| Phone Number | First Name | Last Name |
|---|
| +2001004027 | Allissa | Zoren |
| +2001004028 | Wendy | Strover |
| +2001004043 | Amii | Porritt |
Testing steps
Now that you’ve done client-side, server-side, and CX implementation, test using the test users.
Inge
Jesse
Penny
Allissa
Wendy
Amii
Use this procedure to test the Prove passive authentication with customer-supplied possession fallback flow with Inge Galier on mobile. This user passes Mobile Auth and returns success=true in the /unify-status response.Prompt Customer
Start the onboarding flow on the initial screen and enter the phone number for Inge Galier.
Initiate Start Request
Your front end sends the possession type to the back end. Your back end calls the /unify endpoint. The response provides an auth token, correlation ID, and success=pending.
Send Auth Token to the Front End
Your back end sends the authToken to the front end. The front end runs Mobile Auth.
Verify Mobile Number
Once the front end finishes the possession check, the back end calls POST /v3/unify-status with the correlation ID to validate the phone number.
Expect success=true, proveId, deviceId, and phoneNumber from Mobile Auth in Sandbox. See POST /v3/unify-status for the full response.You have a successful flow and a Prove key tied to this phone number. Sending this user through again bypasses the possession check due to the Prove key. Send the user on through your authenticated flow. Follow these steps to test the Prove Unified Authentication flow with Jesse Mashro on mobile. This user fails the Unified Authentication flow using Mobile Auth and return success=false in the /unify-status response.Follow this flow when testing Prove passive authentication with customer-supplied possession fallback.
Prompt Customer
Start the onboarding flow on the initial screen and enter the phone number for Jesse Mashro.
Initiate Start Request
Your front end sends the phone number and possession type to the back end. Your back end sends the phone number to the /unify endpoint. The response provides an auth token, correlation ID, and success=pending.
Send Auth Token to the Front End
Your back end sends the authToken to the front end. The front end fails Mobile Auth and OTP without prompting.
Verify Mobile Number
Once the front end finishes the possession check, the back end calls POST /v3/unify-status with the correlation ID to validate the phone number.
Expect success=false and phoneNumber. See POST /v3/unify-status.The test user failed. Send the user through your exception process. If you are testing the reputation check flow by sending checkReputation=true in the /unify request, Penny fails the reputation check and returns success=false in the final response.
Follow these steps to test the Prove Unified Authentication flow with Penny Jowers on mobile with customer-supplied possession fallback. This user fails Mobile Auth but passes after a successful customer OTP and returns success=true in the /unify-bind response.Prompt Customer
Start the onboarding flow on the initial screen and enter the phone number for Penny Jowers.
Initiate Start Request
Your front end sends the phone number and possession type to the back end. Your back end sends the phone number to the /unify endpoint. The response provides an auth token, correlation ID, and success=pending.
Send Auth Token to the Front End
Your back end sends the authToken to the front end. The front end attempts Mobile Auth, which fails.
Verify Mobile Number
The back end then calls the /unify-status endpoint with the correlation ID to validate the phone number. The response provides success=possession_required reminding you to perform your own possession check.
Perform Your Own Possession Check
Perform your own possession check outside of Prove’s system. If the consumer fails, end the flow. If the consumer passes, then proceed to Bind Prove Key.
Bind Prove Key
The back end calls POST /v3/unify-bind with the correlation ID.
Expect success=true, proveId, and phoneNumber in Sandbox. See POST /v3/unify-bind for the full response.You have a successful flow and a Prove key tied to this phone number. Sending this user through again bypasses the possession check due to the Prove key. Send the user on through your authenticated flow. Follow these steps to test the Prove Unified Authentication flow with Allissa Zoren on mobile. This user passes Mobile Auth and returns success=true in the /unify-status response.Follow this flow when testing Prove passive authentication with customer-supplied possession fallback.
Prompt Customer
Start the onboarding flow on the initial screen and enter the phone number for Allissa Zoren.
Initiate Start Request
Your front end sends the possession type to the back end. Your back end calls the /unify endpoint. The response provides an auth token, correlation ID, and success=pending.
Send Auth Token to the Front End
Your back end sends the authToken to the front end. The front end runs Mobile Auth.
Verify Mobile Number
Once the front end finishes the possession check, the back end calls POST /v3/unify-status with the correlation ID to validate the phone number.
Expect success=true, proveId, deviceId, and phoneNumber from Mobile Auth in Sandbox. See POST /v3/unify-status for the full response.You have a successful flow and a Prove key tied to this phone number. Sending this user through again bypasses the possession check due to the Prove key. Send the user on through your authenticated flow. Follow these steps to test the Prove Unified Authentication flow with Wendy Strover on mobile. This user fails Mobile Auth and return success=false in the /unify-status response.Follow this flow when testing Prove passive authentication with customer-supplied possession fallback.
Prompt Customer
Start the onboarding flow on the initial screen and enter the phone number for Wendy Strover.
Initiate Start Request
Your front end sends the phone number and possession type to the back end. Your back end sends the phone number to the /unify endpoint. The response provides an auth token, correlation ID, and success=pending.
Send Auth Token to the Front End
Your back end sends the authToken to the front end. The front end fails Mobile Auth.
If you are testing the reputation check flow by sending checkReputation=true in the /unify request, Amii fails the reputation check and returns success=false in the final response.
Follow these steps to test the Prove Unified Authentication flow with Amii Porritt on mobile with customer-supplied possession fallback. This user fails Mobile Auth but passes after a successful customer possession check and returns success=true in the /unify-bind response.Prompt Customer
Start the onboarding flow on the initial screen and enter the phone number for Amii Porritt.
Initiate Start Request
Your front end sends the phone number and possession type to the back end. Your back end sends the phone number to the /unify endpoint. The response provides an auth token, correlation ID, and success=pending.
Send Auth Token to the Front End
Your back end sends the authToken to the front end. The front end attempts Mobile Auth, which fails.
Verify Mobile Number
The back end then calls the /unify-status endpoint with the correlation ID to validate the phone number. The response provides success=possession_required reminding you to perform your own possession check.
Perform Your Own Possession Check
Perform your own possession check outside of Prove’s system. If the consumer fails, end the flow. If the consumer passes, then proceed to Bind Prove Key.
Bind Prove Key
The back end calls POST /v3/unify-bind with the correlation ID.
Expect success=true, proveId, and phoneNumber in Sandbox. See POST /v3/unify-bind for the full response.You have a successful flow and a Prove key tied to this phone number. Sending this user through again bypasses the possession check due to the Prove key. Send the user on through your authenticated flow.