Skip to content

System Requirements

Minimum Requirements

Component Requirement
OS Linux x86_64 (Ubuntu 20.04+)
CPU 4 cores
Memory 4 GB RAM
Disk 1 GB free space
Component Recommendation
OS Ubuntu 24.04 LTS
CPU 8+ cores
Memory 8 GB+ RAM
Network Low-latency connection
Storage SSD for logs

Network Requirements

Outbound Connectivity

The service must reach:

  • Facephi license servers (for license validation)

License Server Access

Required IPs and ports:

IP Port Protocol
52.223.22.71 443 TCP/IP
35.71.188.31 443 TCP/IP
75.2.113.112 443 TCP/IP
99.83.149.57 443 TCP/IP

Required URLs:

  • https://api.cryptlex.com:443
  • https://api.eu.cryptlex.com:443

Configure firewall rules to allow outbound HTTPS traffic to these endpoints.

Deployment Architecture

The IAD Service operates as a stateless REST API that evaluates capture payloads and returns a public Facephi contract:

Client → IAD Service (Port 6982)
  • Multiple service instances can run behind a load balancer
  • Each instance maintains the internal resources required for capture processing
  • No session state is stored in the service

Public API Compatibility

Breaking change notice (2.0.0) The public REST API exposed by version 2.0.0 breaks compatibility with the 1.x.x series. This affects the wire contract, not only the documentation. Integrations must migrate endpoint paths, multipart field names, and successful response parsing rules.

Integration area 1.x.x 2.0.0
Liveness endpoint /api/v1/iad/check-capture /api/v1/iad/liveness/evaluate
Extraction endpoint /api/v1/iad/extract-image /api/v1/iad/extract
Multipart request field file capture
Successful liveness payload Legacy private fields Facephi public fields

Experimental Replay Attack Mitigation

The service can enforce a freshness window on incoming capture payloads. This experimental protection is disabled by default.

  • Enable it with FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED=true
  • Adjust the freshness window with FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME=<seconds>
  • Default freshness window: 300 seconds
  • Applies to capture-processing endpoints such as POST /api/v1/iad/liveness/evaluate and POST /api/v1/iad/extract
  • When the freshness window is exceeded, the public API returns HTTP 400 with message equal to Replay attack detected

This feature is configured at startup through environment variables. It is not part of config.json and is not exposed through GET|POST /api/v1/iad/config.

Performance Characteristics

Metric Typical Value
Latency < 100ms
Throughput Depends on service sizing and capture-processing capacity
Concurrent connections Limited by number_of_threads and engine_pool_size
Max request size Configurable via client_max_body_size

Security Considerations

  • Deploy behind a reverse proxy or API gateway
  • Enable SSL/TLS for all communications
  • Protect license file with appropriate permissions (chmod 644)
  • Use firewall rules to restrict inbound connections

Facephi-Normalized Error Messages

For POST /api/v1/iad/liveness/evaluate, capture validation failures are normalized to public message values including:

  • NoneBecauseFaceTooClose
  • NoneBecauseFaceNotFound
  • NoneBecauseFaceCropped
  • NoneBecauseFaceOccluded
  • NoneBecauseTooManyFaces
  • NoneBecauseAngleTooLarge
  • NoneBecauseFaceTooSmall
  • NoneBecauseFaceTooCloseToBorder
  • NoneBecauseEyesClosed
  • NoneBecauseImageDataError
  • NoneBecauseLicenseError
  • Replay attack detected
  • ErrorProcessing

For POST /api/v1/iad/extract, parse and decrypt payload failures are returned as NoneBecauseImageDataError; expired captures rejected by replay protection return Replay attack detected; unclassified extraction failures are returned as ErrorFacialImage.

Successful liveness responses are mapped to the public fields diagnostic, reason, probability, score, sdkDuration, and queueDuration. Private implementation fields are not exposed.

Possible values for reason in POST /api/v1/iad/liveness/evaluate are:

  • None
  • Unknown
  • UntrustedEnvironment
  • SuspiciousActivity
  • UntrustedDevice
  • SdkIntegrityViolation
  • UntrustedCorruptedPayload
  • UntrustedContent
  • UntrustedContentLowConfidence

The meaning of each public reason value is:

reason Meaning
None The capture was accepted as Live and no rejection reason applies.
Unknown The service could not map the response to a documented public rejection reason.
UntrustedEnvironment The capture was rejected because the runtime environment is not considered trusted.
SuspiciousActivity The capture was rejected because the device showed activity patterns associated with an attack.
UntrustedDevice The capture was rejected because the device could not be trusted as the device it claims to be.
SdkIntegrityViolation The capture was rejected because the capture SDK or its libraries appear to have been altered.
UntrustedCorruptedPayload The capture was rejected because the payload appears corrupted or tampered with.
UntrustedContent The capture was rejected because an injection attack was detected.
UntrustedContentLowConfidence The capture was rejected because the service detected signs of an injection attack with lower confidence; it should still be treated as a rejection.