> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/finger/technical_documentation/technical_specifications.md).

# 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.