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.

JWT Authentication

JWT authentication can be enabled at startup through either config.json or FACEPHI_IAD_REST_AUTH_* environment variables.

  • Supported startup keys: auth_enabled, auth_jwt_secret, auth_accept_authorization_header, auth_accept_api_key_header, auth_api_key_header_name
  • GET /api/v1/iad/config omits those keys from the public configuration view
  • POST /api/v1/iad/config rejects those keys and cannot be used to rotate JWT auth settings at runtime

Detailed Capture Information (longDetails)

POST /api/v1/iad/liveness/evaluate accepts an optional multipart text field longDetails in the same multipart/form-data body as capture.

  • Accepted values are true and false (case-insensitive, trimmed).
  • When the field is absent, empty, or false, the endpoint returns the standard public liveness payload.
  • Any other value is rejected with HTTP 400.

When longDetails=true, the service correlates the engine request with an internally generated correlation-id header and performs a best-effort lookup against the engine /bi_records endpoint. The successful response includes top-level additionalInfo only when all of the following are true:

  1. engine_bi_records_enabled resolves to true.
  2. engine_url points to an IAD Server that exposes both /check_capture_liveness and /bi_records.
  3. The matching BI record is found before engine_bi_records_timeout_ms expires.

The BI lookup uses the current UTC date window when querying /bi_records, so the service host and the IAD Server should keep synchronized clocks. If BI retrieval is disabled, the endpoint still returns the standard liveness payload without additionalInfo.

In the Docker flow where the service launches the embedded engine itself, logger_long_detail=true or FACEPHI_IAD_LOGGER_LONG_DETAIL=true is also a valid way to activate the child-engine BI data path because src/App.cpp injects IAD_SERVER_BI_LOGS_ENABLED=true and a default BI logs path into that child process unless those internal variables were already defined. The same effect can be achieved by exporting IAD_SERVER_BI_LOGS_ENABLED and optionally IAD_SERVER_BI_LOGS_PATH before service startup. In external-engine deployments, the equivalent BI logging capability must be configured on that engine deployment directly.

The BI retrieval settings live in the service configuration (/app/config/config.json or POST /api/v1/iad/config) and can be overridden with FACEPHI_IAD_ENGINE_BI_RECORDS_* environment variables.

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
  • Prefer injecting auth_jwt_secret through environment variables or a secret store instead of committing it to files
  • 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, optional faceProbability, sdkDuration, and queueDuration. When the client sends longDetails=true and BI retrieval succeeds, the response may also include a top-level additionalInfo object with provider BI data. Legacy private fields and raw engine payloads are otherwise 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.