Skip to main content

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

This authentication type only applies to mobile channels.
1

Initialize the Flow

Send a request to your back end server with the phone number and possessionType=none to start the flow. See POST /v3/unify for optional fields (for example rebind, deviceId, proveId) and the full response.
// Send the Unify request.
rspUnify, err := client.V3.V3UnifyRequest(ctx, &components.V3UnifyRequest{
  PhoneNumber:    "2001004014",
  PossessionType: "none",
})
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.
2

Authenticate

Initialize the client-side SDK to place a Prove Key on the device or to check whether a Prove Key is bound.
async function authenticate(isMobileWeb, authToken) {
  // Set up the authenticator for the mobile flow.
  let builder = new proveAuth.AuthenticatorBuilder();

  builder = builder
    .withAuthFinishStep((input) => verify(input.authId));
  
  const authenticator = builder.build();

  // Authenticate with the authToken.
  return authenticator.authenticate(authToken);
  }
3

Verify Mobile Number

In the AuthFinishStep of the client SDK, have the function make a call to an endpoint on your back end server. Your backend server should then call 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 (for example possession_required) to decide whether to run the possession step and POST /v3/unify-bind. See POST /v3/unify-status for the full response schema. Interpret evaluation using the Global Fraud Policy.
4

Perform Possession Check

Your app must perform a customer-supplied possession check such as SMS OTP. Only proceed to the next step if the possession check passes.
5

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.

​
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.
Phone NumberFirst NameLast Name
2001004018BarbaraanneCanet
After initial short-term testing, implement the client-side SDK and use the remaining test users to test your implementation.

​
Unified Auth test users

Follow the Testing Steps for expected behavior per step. These users allow you to test “Prove Possession” and “Customer-Supplied Possession with Force Bind” flows.
Phone NumberFirst NameLast Name
2001004014LorantNerger
2001004015LaneyDyball

​
Testing steps

Now that you’ve done client-side, server-side, and CX implementation, test using the test users.
Follow these steps to test the Prove Unified Authentication flow with Lorant Nerger using customer-supplied possession. This user passes the entire Unified Authentication flow using the customer’s possession and return success=true in the /unify-bind response.
1

Prompt Customer

Start the onboarding flow on the initial screen and enter the phone number for Lorant Nerger.
2

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

Verify Mobile Number

The back end then calls POST /v3/unify-status with the correlation ID to validate the phone number. Expect success=possession_required (Prove is not performing the possession check). See POST /v3/unify-status.
4

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

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

Related topics

Implement Customer Possession With Force BindImplement Prove Passive Authentication With Customer-Supplied Possession Fallback