Integration Flow

The complete behavioral scoring flow involves your app, your backend, the SDK and the TrustVision API:

Your App + SDK (device)            Your Backend                 TrustVision API
     |                                  |                              |
     |-- initialize(config) ----------->| (SDK generates the device    |
     |   bootstrapKeyId +               |  RSA key pair on the device) |
     |   bootstrapPublicKey             |                              |
     |                                  |                              |
     |-- getRegistrationStatus()        |                              |
     |   = Required(deviceId,           |                              |
     |     bootstrapKeyId, encrypted    |                              |
     |     device public key, ...)      |                              |
     |--- registration values --------->|                              |
     |                                  |--- POST /v1/register_device ->|
     |                                  |<-- customer_user_device_id ---|
     |<-- customer_user_device_id ------|                              |
     |-- markDeviceRegistered(...)      |                              |
     |                                  |                              |
     |-- startCollect() --- POST /v1/behavior/create_challenge ------->|
     |<------------------- challenge_id, nonce, server_public_key -----|
     |-- (collect) ------- POST /v1/behavior/push_event_batch -------->|
     |                                  |                              |
     |-- finalizeCollect()              |                              |
     |   = TSFinalizeResult.challengeId |                              |
     |--- challengeId + action -------->|                              |
     |                                  |--- POST /v1/behavior/score -->|
     |                                  |<-- behavior_score, decision --|

1. TrustVision issues a bootstrap key pair (RSA-2048) for your environment and gives you its id and public key. Pass them to the SDK as bootstrapKeyId / bootstrapPublicKey; your backend sends the same id as key_pair_id to register_device. The private half never leaves TrustVision.
2. The SDK generates the device key pair on the device (Android Keystore, iOS Keychain) during initialize(). The private key never leaves the device. The SDK encrypts the device public key with the bootstrap public key.
3. Your app asks the SDK whether registration is needed with getRegistrationStatus(). On Required, it sends the returned values (deviceId, bootstrapKeyId, encryptedDevicePublicKeyPayload, encryptedSecretKey, cusUserId) to your backend.
4. Your backend calls POST /v1/register_device with them and returns data.customer_user_device_id to the app. The app hands it to the SDK with markDeviceRegistered(true, customerUserDeviceId, cusUserId) — or reportRegistrationFailed(statusCode) on failure.
5. The SDK calls POST /v1/behavior/create_challenge when collection starts, which returns a challenge ID, nonce, and server public key.
6. The SDK collects behavioral data (touch, typing, sensors) and pushes batches via POST /v1/behavior/push_event_batch.
7. At the action you want to score, the app calls finalizeCollect(). Its result's challengeId is the session reference: send it to your backend together with the action.
8. Your backend calls POST /v1/behavior/score with that value as challenge_id (and optional transaction_data) to get the behavior score, risk level, and — when the policy check is enabled — the recommended decision.final_action.
9. On the user's first session, step 8 enrolls the behavioral baseline instead of scoring (more_details.is_first_session: true); real scoring starts from the second session.

When to register again

getRegistrationStatus() returns Required again — and your backend must call register_device again — when:

After a rejected registration (any HTTP answer, reported with reportRegistrationFailed), the SDK returns CoolingDown for that cus_user_id for 10 minutes; a new sign-in (setCusUserId) clears it. Every register_device call creates a new customer_user_device record, so do not call it when the status is Registered.