Technical specifications

Minimum requirements

Component	Requirement
OS	Linux x86_64 (Ubuntu 20.04+)
CPU	4 cores
Memory	4 GB RAM
Disk	1 GB of free space

Recommended for production

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 be able to 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

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 necessary for capture processing

• The service does not store session state

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 communication contract, not just the documentation. Integrations must migrate the Endpoint routes, the multipart field names, and the parsing rules for correct responses.

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
Valid Liveness payload	Inherited private fields	Facephi public fields

Experimental replay attack mitigation

The service can apply a freshness window to 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

• It 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 functionality is configured at startup using environment variables. It is not part of config.json nor exposed through GET|POST /api/v1/iad/config.

JWT authentication

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

• 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 authentication configuration at runtime

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
Maximum request size	Configurable via client_max_body_size

Security considerations

• Deploy behind a reverse proxy or an API gateway

• Enable SSL/TLS for all communications

• Prefer injecting auth_jwt_secret via environment variables or a secrets manager instead of including it in files

• Protect the license file with the appropriate permissions (chmod 644)

• Use firewall rules to restrict incoming connections

Facephi-normalized error messages

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

• NoneBecauseFaceTooClose

• NoneBecauseFaceNotFound

• NoneBecauseFaceCropped

• NoneBecauseFaceOccluded

• NoneBecauseTooManyFaces

• NoneBecauseAngleTooLarge

• NoneBecauseFaceTooSmall

• NoneBecauseFaceTooCloseToBorder

• NoneBecauseEyesClosed

• NoneBecauseImageDataError

• NoneBecauseLicenseError

• Replay attack detected

• ErrorProcessing

For POST /api/v1/iad/extract, payload parsing and decryption 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, faceProbability optional, sdkDuration and queueDuration. The inherited private fields and the engine's raw payloads are not exposed.

The 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 value of reason 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 to be the one 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 to be 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.