ENROLL

The PrivateID® Session API leverages state-of-the-art, patented homomorphic tokenization and advanced authentication mechanisms to ensure that raw biometric data is never transmitted or stored. All interactions are cryptographically bound using a combination of an API key (for billing only) and robust client credentials (clientID/clientSecret or SLC). This section details the machine-to-machine authentication infrastructure and the ENROLL operation for secure facial biometric enrollment.

Overview

The ENROLL operation is responsible for enrolling a new user’s homomorphic token and optional FIDO Passkey through a secure, on-device process. The procedure entails:

1. Biometric Capture & On-device Preprocessing:
   • The local device captures the user’s facial image using an integrated sensor.
   • On-device biometric pre-processing pipeline (e.g., face detection, crop and align, biometric validation and liveness models) isolates and validates the biometric.
2. Homomorphic Token Generation On-device:

   • The biometric data is transformed on-device into a secure, anonymized Homomorphic Token.

   • This Homomorphic Token allows for similarity computations on ciphertexts without the possibility to invert, ensuring privacy-preserving matching.

3. Data Purging:

   • All biometric information including the raw biometric input is immediately purged from volatile memory on the local device and never stored or transmitted, minimizing the risk of data leakage. In some cases, customers may return this user selfie in the Webhook to comply with anti-fraud or regulatory requirements.

4. Optional Token Transmission:

   • The anonymized homomorphic token is optionally transmitted to the server for persistent storage.

5. Session Metadata:
   • Additional parameters such as sessionExpiry , deviceInfo , and transactionID can be included to provide context and enforce session limits.

Endpoint

  POST /v2/verification-session

Request Body

In addition to the base parameters, we include additional parameters for enhanced session control and device-level auditability:

  {
    "type": "ENROLL",
    "redirectURL": "https://your-app.com/callback",
    "callback": {
      "url": "https://your-api.com/webhook",
      "headers": {
        "authorization": "Bearer YOUR_TOKEN"
      }
    },
    "locale": "en-US",  //optional - your user locale, if known
    "enableDesktop": false,
    "estimateAge": true,    //Returns Facial Age Estimation (FAE) Level 3 Certified by ACCS
    "sendImages": false,
    "transactionID": "txn-abcdef123456", // Client-generated transaction identifier.
    "deviceInfo": {                      // Optional device metadata.
        "os": "iOS 15.0",
        "model": "iPhone 13",
        "resolution": "2532x1170"
    },
    "debugMode": false,                  // Enable additional logging for troubleshooting.
    "requirements": [                    // Enables usage of different scenarios
      "face",
      "identity_document"
      "passkey",
    ],
  }

Parameter Details

Success Response

A successful registration returns a JSON payload including a unique session identifier and a launch URL for the biometric process:

{
  "launchUrl": "https://verify.privateid.com/start?sessionId=2fbbb4a3-1392-43c4-8d12-f61ff44e4efb",
  "sessionId": "2fbbb4a3-1392-43c4-8d12-f61ff44e4efb"
}

Note: The issuedToken represents the Homomorphic Token, which can be used for subsequent SIGN-IN or VERIFY operations.

Failure Response

{
  "statusCode": 401,
  "message": "Invalid API key"
}

Webhook Response

Success

{
  "sessionId": "ed36ca71-c1e0-4eaa-a517-a405bc111077",
  "status": "SUCCESS",
  "transactionId": "dac57c75-0ed8-40fa-b40e-f0620dbb9444",
  "puid": "NLOaU9FP-RvN7-TAmR-jR9T-nKt75q9L20ad",
  "guid": "wbvH0V3u-tntc-XjWO-Cr8F-ygZHXi6rpu3d",
  "identityInformation": {
    "documentType": "drivers_license",
    "verificationDate": "1743795933839"
  },
  "contactInformation": {
    "email": "test@test.com",
    "phone": "1111111111"
  },
  "message": "here will be the message",
  "indicators": {
    "headless": {
      "webdriver": false,        // WebDriver automation detection (Selenium, Puppeteer)
      "userAgent": false,        // Suspicious/modified user agent strings
      "webGL": false,           // Missing/inconsistent WebGL rendering
      "phantom": false,         // PhantomJS headless browser detection
      "selenium": false,        // Selenium automation framework detection
      "chrome": false,          // Chrome automation flags/properties
      "permissions": false,     // Unusual permission states in headless mode
      "plugins": false,         // Missing/suspicious plugin configurations
      "languages": false,       // Inconsistent language settings
      "webRTC": false,          // WebRTC availability inconsistencies
      "notification": false,    // Notification API availability issues
      "deviceMemory": false,    // Suspicious device memory reporting
      "connectionType": false,  // Unusual network connection reporting
      "timing": false          // Suspicious timing patterns vs human behavior
    },
    "virtualCamera": {
      "virtualCameraSoftware": false,  // OBS, ManyCam, XSplit detection
      "suspiciousLabels": false,       // Fake camera device names/labels
      "noMediaDevices": false,         // No physical media devices present
      "mediaDevicesError": false       // Media device enumeration errors
    },
    "browserAnomalies": {
      "missingWebAPIs": false,         // Standard web APIs not present
      "inconsistentFingerprint": false, // Browser fingerprint mismatches
      "automationProperties": false    // Non-WebDriver automation artifacts
    }
  }
}

Browser Security Indicators

The indicators field provides browser security analysis to detect fraud attempts and automated verification tools. This field is optional and only included when browser data is available from the enrollment session.

Key Categories:

• headless: Detects automated browsers and headless tools (WebDriver, Selenium, etc.)
• virtualCamera: Identifies fake camera software (OBS, ManyCam) and suspicious video sources
• browserAnomalies: Detects inconsistent browser environments and automation properties

Values: true = suspicious activity detected, false = no issues detected

For comprehensive technical details on how each indicator works, detection methods, and risk levels, see the Detailed Indicator Reference.

Cryptographic Considerations for ENROLL

Homomorphic Tokenization: Private Identity employs homomorphic tokenization to generate deep harmonic embeddings that enable secure, limited search and matching operations on ciphertexts without allowing decryption, thus preserving data confidentiality. This advanced cryptographic architecture centers on generating tokens that are computationally irreversible and collision-resistant through the combined application of preimage resistance, second preimage resistance, and collision resistance. By integrating a time-based salt within an AES256 encryption framework, the system produces non-deterministic, fixed-size outputs (ranging from 1KB to 16KB) with each token generated in as little as 20ms via neural network cryptography. Despite the inherent limitation that no homomorphic token ciphertext is fully IND-CCA secure, extensive research confirms that Private Identity’s embeddings remain opaque, with any inversion or decryption attempts yielding no sensitive information. Further robustness is achieved through the Private ID Edge Encryption Service, which executes immutable, compiled native C++ code and proprietary deep neural networks in an isolated, stack-based virtual machine, reinforced by three additional layers of cryptography to secure backend communications and the entire authentication process. Immediately after token generation, raw biometric data is purged from volatile memory in a "fire and forget" approach, thereby minimizing the risk of residual data exposure.