Technical specifications

Compatibility Notice

IMPORTANT - INCOMPATIBLE CHANGE (BREAKING CHANGE) (2.0.0)

The payload REST contract for fingerprint operations changed in version 2.0.0 and is not compatible with 1.x.x client payloads.

Minimum requirements

Component	Requirement
OS	Linux x86_64
CPU	4 cores
Memory	4 GB of RAM
Disk	2 GB of free space

Recommended for production

Component	Recommendation
OS	Ubuntu LTS
CPU	8 or more cores
Memory	8 GB or more of RAM
Storage	SSD for logs and container layers
Network	Low-latency connectivity with the required fingerprint processing services

Runtime and compilation constraints

• Supported architecture: x86_64

• Supported target operating system: Linux

• Container base runtime: Ubuntu 20.04

Service architecture

The service acts as a stateless Rest API adaptation layer:

Client application -> Facephi Finger Service -> Facephi Fingerprint Processing

Features:

• No session state is stored in the API layer

• Public requests are validated and normalized before processing

• Processing responses are translated back to the public contract

• Suitable for horizontal scaling behind a load balancer

Endpoint availability by role

Role	Endpoints
master	extract, authenticate, health, version, metrics, config
worker	health, version, metrics, config

Supported image formats (public fingerprint endpoints)

For image-based requests in:

• POST /api/v1/finger/extract (image)

• POST /api/v1/finger/authenticate (image1, image2)

the supported fingerprint image formats are:

• wsq

• bmp

• png

• jpg

• jp2

Configuration model

Order of precedence

From highest to lowest priority:

1. Environment variables

2. config.json

3. Service default values

Runtime configuration groups

• REST manager settings: listening port, threads, timeout, body size, logging

• REST authentication settings: JWT enablement, HS256 secret, accepted token headers

• Processing settings: URL, connection/request timeout, retries, pool size, SSL verification

• Topology settings: role (master/worker), list of processing services, master node discovery address

• License usage counters: enabled through the license metadata key ActivateUsageCounters

JWT authentication settings are applied during service startup. Changing them requires restarting the service.

Usage counters

• GET /api/v1/finger/metrics exposes operation usage counters extract and authenticate completed successfully.

• The response fields are: usageCountersEnabled, extractCount, authenticateCount, totalCount.

• The license metering attributes used by the service are FingerExtractCounter and FingerAuthenticateCounter.

• totalCount is calculated as extractCount + authenticateCount.

Performance considerations

Dimension	Guidance
Throughput	Scales with engine capacity and connection pool size
Latency	Affected by engine request timeout and retries
Concurrency	Influenced by number_of_threads and engine_pool_size
Payload size	Controlled by client_max_body_size

Operational notes

• During container startup, processing services may require a warm-up period.

• Health checks validate the service context, the license, and processing availability.

• In cluster-oriented deployments, ensure a consistent discovery configuration across nodes.

Security recommendations

• Deploy behind a reverse proxy or an API gateway.

• Restrict inbound access to trusted networks.

• Use TLS termination at the gateway or load balancer.

• Protect mounted license and configuration files with least-privilege permissions.

• Keep auth_jwt_secret in a secrets store or injected as an environment variable instead of including it directly in images.

• When JWT is enabled, use HS256 tokens with a valid claim exp and protect all non-public endpoints.

• Enable SSL verification for communication with the processing backend when the infrastructure allows it.

The public endpoints that remain unauthenticated are GET /api/v1/finger/health, GET /api/v1/finger/version and the preflight requests OPTIONS.

Logging and monitoring

Use these endpoints for liveness checks:

• GET /api/v1/finger/health

• GET /api/v1/finger/version

• GET /api/v1/finger/metrics

Configure logs with:

• logger_level

• logger_path

• logger_rotation

• logger_max_files

Compatibility notes

• The API payloads for fingerprint operations use public contract 2.0.0.

• Internal field names are not exposed in public responses.

• The management endpoint payloads are stable and documented in OpenAPI.