Skip to content

Release Notes — Version 2.0.0

Release Date: May 25, 2026

Overview

Facephi IAD Service 2.0.0 is a major release that introduces a new public REST contract for liveness and extraction workflows. This release is not backward-compatible with the 1.x.x series.

Breaking Changes

Public Endpoint Changes

1.x.x Endpoint 2.0.0 Endpoint
POST /api/v1/iad/check-capture POST /api/v1/iad/liveness/evaluate
POST /api/v1/iad/extract-image POST /api/v1/iad/extract

Multipart Contract Changes

  • Multipart requests now require the capture field.
  • Requests that only include legacy file without capture are rejected.

Success Payload Changes

  • Public success payloads now expose Facephi-style fields such as diagnostic, reason, probability, score, faceProbability, sdkDuration, and queueDuration.
  • Legacy Engine-shaped fields such as capture_liveness, capture_type, rejection, and mime_type are no longer returned in public success responses.

What's New

Public Contract Normalization

  • Liveness responses are mapped to a stable public contract focused on Facephi integration fields.
  • Public liveness reason values are documented explicitly as None, Unknown, UntrustedEnvironment, SuspiciousActivity, UntrustedDevice, SdkIntegrityViolation, UntrustedCorruptedPayload, UntrustedContent, and UntrustedContentLowConfidence.
  • Capture validation errors are normalized to Facephi/SelphID-style values.

Experimental Replay Attack Mitigation

  • The service can enforce a freshness window on incoming capture payloads.
  • Startup environment variables FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED and FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME enable and configure the feature.
  • The default freshness window is 300 seconds.
  • When the freshness window is exceeded, capture-processing endpoints return HTTP 400 with message equal to Replay attack detected.

Reliability and Runtime Behavior

  • Service startup failures are propagated to main instead of terminating from startup internals.
  • Signal handling no longer performs non-signal-safe operations such as logging, shutdown logic, or std::exit directly from handlers.

Quality Assurance

  • Added unit tests for public success payload mapping and prevention of private field leaks.
  • Added unit tests to verify required multipart field behavior for capture.

Migration Guide (From 1.x.x)

  1. Update endpoint paths in client integrations.
  2. Update multipart form field names from file to capture.
  3. Update response parsing for successful liveness requests to use the new public fields.
  4. Validate integration behavior with GET /api/v1/iad/version and end-to-end tests in your environment.

Deployment

docker pull facephicorp.jfrog.io/docker-core-pro-fphi/facephi-iad-service:2.0.0

docker run -d \
  -p 6982:6982 \
  -v /path/to/license:/app/license \
  -v /path/to/config:/app/config \
  --name iad-service \
  facephicorp.jfrog.io/docker-core-pro-fphi/facephi-iad-service:2.0.0

Requirements

Component Requirement
Operating System Linux x86_64 (Ubuntu 24.04 recommended)
License Valid Facephi license file
Docker For containerized deployment

Support

For technical support, contact your Facephi representative.

Documentation