> 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.md).

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

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

Response:

```json
{
  "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:

```json
{
  "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:

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

Request using images:

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

Response:

```json
{
  "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

```bash
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

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

Typical responses:

```json
{ "message": "Healthy" }
```

```json
{ "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`:

```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](/docs.facephi-en/sdks/backend-sdk/finger/installation/installation_instructions.md)
* [Technical Specifications](/docs.facephi-en/sdks/backend-sdk/finger/technical_documentation/technical_specifications.md)
* [API Reference](https://github.com/facephi/facephi-gitbook-docs/tree/master/docs/sdks/backend-sdk/finger/technical_documentation/openapi.yaml)
* [Change Log](/docs.facephi-en/sdks/backend-sdk/finger/changelog.md)

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