Authenticate two fingerprints (1:1)

IMPORTANT - BREAKING CHANGE (2.0.0). This endpoint is not compatible with 1.x.x. It accepts images and templates through public fields and returns the public fields authStatus and similarity.

Compares a probe fingerprint (side 1) with a gallery fingerprint (side 2). Supported input formats for image1 and image2: wsq, bmp, png, jpg, jp2. Only available on master nodes.

Validation errors (HTTP 400), checked in this order before the fingerprints are compared:

Case	message
The body is not a JSON object sent as application/json	Value, object or array expected.
A field is present but is not a string, or is empty	Key <field> is not a string, Key <field> is empty string
options is not an object	Key options is not an object
options.dpi or options.authThreshold is not an unsigned integer	Key dpi is not an unsigned integer, Key authThreshold is not an unsigned integer
The body is an empty JSON object	Empty payload
Neither image1 nor fingerTemplate1 is sent	Missing required field: image1 or fingerTemplate1
Both image1 and fingerTemplate1 are sent	Provide exactly one of image1 or fingerTemplate1
The side 1 value is not valid Base64	Malformed Base64 input
Neither position1 nor position is sent	Missing required field: position
The side 1 position is not one of the documented values	Invalid finger position
Neither image2 nor fingerTemplate2 is sent	Missing required field: image2 or fingerTemplate2
Both image2 and fingerTemplate2 are sent	Provide exactly one of image2 or fingerTemplate2
The side 2 value is not valid Base64	Malformed Base64 input
Neither position2 nor position is sent	Missing required field: position
The side 2 position is not one of the documented values	Invalid finger position
options.dpi is outside 250-1000	Invalid dpi value
options.authThreshold is greater than 100	Invalid authThreshold value

Processing errors (HTTP 400):

message	Cause
Finger verification failed	The processing components could not compare the fingerprints
Invalid response from Engine	The processing components returned a response the service cannot interpret
Fingerprint processing communication error: <detail>	The processing components could not be reached or answered with an HTTP error. <detail> is, for example, Too many retries when they kept failing after the retries configured in engine_max_retries
Service not initialized, Service not configured	The service is not ready yet

A Negative result is returned with HTTP 200. Only successful authentications increase the usage counters and feed the quality figures of GET /api/v1/finger/metrics.

post

Autorizações

AuthorizationstringObrigatório

HS256 JWT signed with auth_jwt_secret and carrying an exp claim, sent as Authorization: Bearer <jwt>. Accepted while auth_accept_authorization_header is true (default). Only enforced when auth_enabled is true.

Corpo

Public 1:1 authentication request. Exactly one source is required on each side:

• Side 1 (probe): image1 or fingerTemplate1
• Side 2 (gallery): image2 or fingerTemplate2

Images and templates can be combined (for example, image1 with fingerTemplate2). The finger position is given either as a shared position or per side with position1 and position2, which take precedence over position for their side.

image1stringOpcional

Probe fingerprint image encoded in Base64 (RFC 4648). Supported formats; wsq, bmp, png, jpg, jp2.

fingerTemplate1stringOpcional

Probe fingerprint template encoded in Base64, as returned by POST /api/v1/finger/extract.

image2stringOpcional

Gallery fingerprint image encoded in Base64 (RFC 4648). Supported formats; wsq, bmp, png, jpg, jp2.

fingerTemplate2stringOpcional

Gallery fingerprint template encoded in Base64, as returned by POST /api/v1/finger/extract.

positionstring · enumOpcional

Public finger position name.

Example: RightIndexValores possíveis:

position1string · enumOpcional

Public finger position name.

Example: RightIndexValores possíveis:

position2string · enumOpcional

Public finger position name.

Example: RightIndexValores possíveis:

Respostas

200

Public authentication response.

application/json

Public 1:1 authentication response.

authStatusstring · enumObrigatório

Positive when similarity is greater than or equal to options.authThreshold, Negative otherwise. A Negative result is a successful authentication (HTTP 200), not an error.

Example: PositiveValores possíveis:

similaritynumber · float · máx: 100Obrigatório

Similarity score between both fingerprints, in the 0-100 range.

Example: 84.65

sdkDurationinteger · int64Obrigatório

Processing time in milliseconds.

Example: 131

queueDurationinteger · int64Obrigatório

Time the request waited in the queue, in milliseconds.

Example: 1

400

The request is invalid or could not be processed. message carries the reason; see the operation description for the values it can take.

application/json

401

JWT authentication is enabled and the request carries no token or an invalid one. message is one of Missing authentication token, JWT token is expired, JWT token does not include exp claim, JWT token validation failed or, when auth_jwt_secret is empty, Authentication secret is not configured.

application/json

404

The route is not registered on this node. The fingerprint operations only exist on nodes started with the master role. This response is produced by the HTTP server and does not carry the standard error body.

413

The request body exceeds client_max_body_size. This response is produced by the HTTP server before the request reaches the service and does not carry the standard error body.

500

Unhandled internal error. exception carries the detail.

application/json

post/api/v1/finger/authenticate

POST /api/v1/finger/authenticate HTTP/1.1
Host: 127.0.0.1:6982/
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 146

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

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