Finger Service

Fingerprint Rest API for template extraction and 1:1 authentication.

Important compatibility notice

IMPORTANT - INCOMPATIBLE CHANGE (BREAKING CHANGE) (2.0.0)

Starting with version 2.0.0, the fingerprint operation endpoints are not compatible with version 1.x.x:

• POST /api/v1/finger/extract

• POST /api/v1/finger/authenticate

Legacy public routes POST /api/v1/finger/create-template and POST /api/v1/finger/verify are not available in version 2.0.0.

The request and response payload formats have changed. Integrations created for version 1.x.x must migrate to the 2.0.0 public contract before upgrading.

Overview

Facephi Finger Service exposes a public API under /api/v1/finger/ with fingerprint-oriented field names such as image, position, fingerTemplate, authStatus and similarity.

Optionally, the public fingerprint and management endpoints can be protected with JWT authentication. It is configured at service startup from config.json or from environment variables FACEPHI_FINGER_REST_*.

For requests that include fingerprint images (image, image1, image2), the supported formats are WSQ, bmp, png, jpg and jp2.

The service provides:

• Fingerprint template extraction

• Fingerprint 1:1 authentication

• Usage counters through GET /api/v1/finger/metrics

• Health, version, and runtime configuration endpoints

Public contract

Extract

Supported image formats for image: WSQ, bmp, png, jpg, jp2.

Request:

{
  "image": "<base64_fingerprint_image>",
  "position": "RightIndex",
  "options": {
    "dpi": 500,
    "scanType": "Plain",
    "includeQuality": true
  }
}

Response:

{
  "fingerTemplate": "<base64_generated_template>",
  "position": "RightIndex",
  "scanType": "Plain",
  "quality": 88,
  "qualityDetails": {
    "nfiq2": 79.0,
    "nfiq": 1.0,
    "score": 88.0
  },
  "sdkDuration": 123,
  "queueDuration": 2
}

Metrics

Response:

{
  "usageCountersEnabled": true,
  "extractCount": 12,
  "authenticateCount": 7,
  "totalCount": 19
}

Notes:

• usageCountersEnabled depends on the license metadata key ActivateUsageCounters.

• extractCount and authenticateCount correspond to the license measurement attributes FingerExtractCounter and FingerAuthenticateCounter.

• totalCount is calculated as extractCount + authenticateCount.

Authenticate

Supported image formats for image1 and image2: WSQ, bmp, png, jpg, jp2.

Request using templates:

{
  "fingerTemplate1": "<base64_probe_template>",
  "fingerTemplate2": "<base64_gallery_template>",
  "position": "RightIndex",
  "options": {
    "authThreshold": 20
  }
}

Request using images:

{
  "image1": "<base64_probe_image>",
  "image2": "<base64_gallery_image>",
  "position": "RightIndex",
  "options": {
    "authThreshold": 20
  }
}

Response:

{
  "authStatus": "Positive",
  "similarity": 84.65,
  "sdkDuration": 131,
  "queueDuration": 1
}

API endpoints

Endpoint	Method	Purpose
/api/v1/finger/extract	POST	Extracts a fingerprint template from a public payload
/api/v1/finger/authenticate	POST	Performs public 1:1 fingerprint authentication
/api/v1/finger/metrics	GET	Gets the usage counters report
/api/v1/finger/version	GET	Service version and license status
/api/v1/finger/health	GET	Service health and availability check
/api/v1/finger/config	GET/POST	Gets or updates the runtime configuration

Quick start

Requirements

Component	Requirement
OS	Linux x86_64
Runtime	Docker is recommended
License	Valid Facephi license file

Docker deployment

docker run -d \
  -p 6982:6982 \
  -v /path/to/license:/app/license \
  -v /path/to/config:/app/config \
  --name finger-service \
  facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service:2.1.0

Verify the deployment

curl http://localhost:6982/api/v1/finger/health
curl http://localhost:6982/api/v1/finger/version

Typical responses:

{ "message": "Healthy" }

{ "message": "2.1.0 Copyright (c) 2026 FacePhi Biometria. All rights reserved." }

When JWT authentication is enabled, health and version remain public while protected endpoints require a valid JWT.

Configuration

Create /app/config/config.json:

{
  "port": 6982,
  "number_of_threads": 1,
  "connection_timeout": 60,
  "keep_alive_request_number": 0,
  "client_max_body_size": 100,
  "logger_level": "info",
  "logger_path": "/app/logs",
  "logger_rotation": "daily",
  "logger_max_files": 7,
  "auth_enabled": false,
  "auth_jwt_secret": "",
  "auth_accept_authorization_header": true,
  "auth_accept_api_key_header": true,
  "auth_api_key_header_name": "x-api-key",
  "engine_connection_timeout": 10000,
  "engine_request_timeout": 60000,
  "engine_max_retries": 3,
  "engine_retry_delay": 1000,
  "engine_verify_ssl": false,
  "engine_verbose": false,
  "engine_pool_size": 4,
  "engine_url": "http://localhost:8080"
}

The JWT configuration is applied during service startup. If you update these values, restart the service.

Documentation

• Installation Guide

• Technical Specifications

• API Reference

• Change Log

Vendor abstraction note

The documentation and public payloads intentionally keep the processing runtime abstracted. Integrations should rely solely on the documented Facephi public contract.

Support

For licenses and Technical Support, contact your Facephi representative.