Behavioral Biometrics (BehavioIQ)
Register a device
Registers a client device for behavioral data collection, creating a customer_user_device record and returning its id.
Request
A server-side call that creates a customer_user_device record. Your backend makes it with the values the SDK returns from getRegistrationStatus() (Required) — see Integration Flow. Each call creates a new record; call it only when the SDK reports that registration is required (when to register again).
| Name | Type | Required | Description |
|---|---|---|---|
key_pair_id | string | Required | UUID of the bootstrap key pair issued by TrustVision — the SDK's bootstrapKeyId. The server decrypts device_public_key with its private half |
device_public_key | string | Required | Base64-encoded RSA public key of the key pair the SDK generated on the device (PKIX/DER format). With protocol: encrypted, the SDK's encryptedDevicePublicKeyPayload |
encrypted_secret_key | string | Optional | RSA-OAEP encrypted AES key — the SDK's encryptedSecretKey (required when protocol is encrypted) |
cus_user_id | string | Required | Your unique identifier for the end user — the cusUserId of the SDK's Required status |
device_id | string | Required | Unique identifier for the device — the SDK's deviceId |
protocol | string | Optional | Empty string (plain) or encrypted. When encrypted, the device_public_key is AES-GCM encrypted and encrypted_secret_key is required |
Sample request
Plain protocol:
{
"key_pair_id": "550e8400-e29b-41d4-a716-446655440000",
"device_public_key": "MIIBIjANBgkqhk...",
"cus_user_id": "user-123",
"device_id": "device-abc-456"
}
Encrypted protocol:
{
"key_pair_id": "550e8400-e29b-41d4-a716-446655440000",
"device_public_key": "<AES-GCM encrypted device public key>",
"encrypted_secret_key": "<RSA-OAEP encrypted AES key>",
"cus_user_id": "user-123",
"device_id": "device-abc-456",
"protocol": "encrypted"
}
Response
data.customer_user_device_id is the id of the new device record — the <customer_user_device_id> an SDK request carries in its Authorization header. Return it to the app, which passes it to the SDK with markDeviceRegistered.
| Field | Type | Description |
|---|---|---|
data.customer_user_device_id | string | UUID of the newly created customer user device |
data.profile_id | string | UUID of the user's behavioral profile for this cus_user_id; empty if it could not be created |
data.status | string | success |
{
"data": {
"customer_user_device_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"profile_id": "0f9e8d7c-6b5a-4321-9876-543210fedcba",
"status": "success"
}
}
Failure codes
Errors arrive in the envelope described under Error Responses, and the codes every Behavioral call can return are listed under Common Error Codes.