> 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-pt-br/sdks/backend-sdk/finger/technical_documentation/api_reference/finger-operations/authenticate-two-fingerprints-1-1.md).

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

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"tags":[{"name":"Finger Operations","description":"Fingerprint template extraction and 1:1 authentication. These endpoints use the public payload contract\nintroduced in 2.0.0 and are only registered on `master` nodes.\n"}],"servers":[{"url":"http://127.0.0.1:6982/"}],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"HS256 JWT signed with `auth_jwt_secret` and carrying an `exp` claim, sent as `Authorization: Bearer <jwt>`.\nAccepted while `auth_accept_authorization_header` is `true` (default). Only enforced when `auth_enabled` is\n`true`.\n"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"The same JWT, sent as is (without the `Bearer` prefix) in the header named by `auth_api_key_header_name`\n(`x-api-key` by default). Accepted while `auth_accept_api_key_header` is `true` (default). Only enforced when\n`auth_enabled` is `true`.\n"}},"schemas":{"AuthenticateRequest":{"type":"object","description":"Public 1:1 authentication request. Exactly one source is required on each side:\n\n- Side 1 (probe): `image1` or `fingerTemplate1`\n- Side 2 (gallery): `image2` or `fingerTemplate2`\n\nImages and templates can be combined (for example, `image1` with `fingerTemplate2`). The finger position is\ngiven either as a shared `position` or per side with `position1` and `position2`, which take precedence over\n`position` for their side.\n","properties":{"image1":{"type":"string","description":"Probe fingerprint image encoded in Base64 (RFC 4648). Supported formats; wsq, bmp, png, jpg, jp2."},"fingerTemplate1":{"type":"string","description":"Probe fingerprint template encoded in Base64, as returned by `POST /api/v1/finger/extract`."},"image2":{"type":"string","description":"Gallery fingerprint image encoded in Base64 (RFC 4648). Supported formats; wsq, bmp, png, jpg, jp2."},"fingerTemplate2":{"type":"string","description":"Gallery fingerprint template encoded in Base64, as returned by `POST /api/v1/finger/extract`."},"position":{"$ref":"#/components/schemas/FingerPosition"},"position1":{"$ref":"#/components/schemas/FingerPosition"},"position2":{"$ref":"#/components/schemas/FingerPosition"},"options":{"$ref":"#/components/schemas/AuthenticateOptions"}}},"FingerPosition":{"type":"string","description":"Public finger position name.","enum":["RightThumb","RightIndex","RightMiddle","RightRing","RightLittle","LeftThumb","LeftIndex","LeftMiddle","LeftRing","LeftLittle"]},"AuthenticateOptions":{"type":"object","description":"Optional tuning parameters of the authentication.","properties":{"dpi":{"type":"integer","description":"Resolution, in dots per inch, of the images sent in `image1` and `image2`.","minimum":250,"maximum":1000,"default":500},"authThreshold":{"type":"integer","description":"Minimum `similarity` for `authStatus` to be `Positive`. It must be an integer between 0 and 100; decimal\nvalues are rejected.\n","minimum":0,"maximum":100,"default":20}}},"AuthenticateResponse":{"type":"object","description":"Public 1:1 authentication response.","required":["authStatus","similarity","sdkDuration","queueDuration"],"properties":{"authStatus":{"type":"string","description":"`Positive` when `similarity` is greater than or equal to `options.authThreshold`, `Negative` otherwise.\nA `Negative` result is a successful authentication (HTTP `200`), not an error.\n","enum":["Positive","Negative"]},"similarity":{"type":"number","format":"float","description":"Similarity score between both fingerprints, in the 0-100 range.","minimum":0,"maximum":100},"sdkDuration":{"type":"integer","format":"int64","description":"Processing time in milliseconds."},"queueDuration":{"type":"integer","format":"int64","description":"Time the request waited in the queue, in milliseconds."}}},"BadRequestResult":{"type":"object","properties":{"status":{"type":"integer"},"error":{"type":"string"},"message":{"type":"string"},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}},"required":["status","error","message","timeStamp"]},"TimeStamp":{"type":"string","description":"UTC date and time in ISO-8601 format with second precision (`YYYY-MM-DDTHH:MM:SSZ`)."},"UnauthorizedResult":{"type":"object","properties":{"status":{"type":"integer"},"error":{"type":"string"},"message":{"type":"string"},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}},"required":["status","error","message","timeStamp"]},"ExceptionResult":{"type":"object","properties":{"status":{"type":"integer"},"error":{"type":"string"},"exception":{"type":"string"},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}},"required":["status","error","exception","timeStamp"]}},"responses":{"BadRequest":{"description":"The request is invalid or could not be processed. `message` carries the reason; see the operation\ndescription for the values it can take.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResult"}}}},"Unauthorized":{"description":"JWT authentication is enabled and the request carries no token or an invalid one. `message` is one of\n`Missing authentication token`, `JWT token is expired`, `JWT token does not include exp claim`,\n`JWT token validation failed` or, when `auth_jwt_secret` is empty, `Authentication secret is not configured`.\n","headers":{"WWW-Authenticate":{"$ref":"#/components/headers/WWW-Authenticate"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResult"}}}},"NotFoundOnWorker":{"description":"The route is not registered on this node. The fingerprint operations only exist on nodes started with the\n`master` role. This response is produced by the HTTP server and does not carry the standard error body.\n"},"PayloadTooLarge":{"description":"The request body exceeds `client_max_body_size`. This response is produced by the HTTP server before the\nrequest reaches the service and does not carry the standard error body.\n"},"InternalError":{"description":"Unhandled internal error. `exception` carries the detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExceptionResult"}}}}},"headers":{"WWW-Authenticate":{"description":"Always `Bearer` on `401` responses.","schema":{"type":"string"}}}},"paths":{"/api/v1/finger/authenticate":{"post":{"summary":"Authenticate two fingerprints (1:1)","description":"**IMPORTANT - BREAKING CHANGE (2.0.0).** This endpoint is not compatible with 1.x.x. It accepts images and\ntemplates through public fields and returns the public fields `authStatus` and `similarity`.\n\nCompares a probe fingerprint (side 1) with a gallery fingerprint (side 2). Supported input formats for\n`image1` and `image2`: wsq, bmp, png, jpg, jp2. Only available on `master` nodes.\n\nValidation errors (HTTP `400`), checked in this order before the fingerprints are compared:\n\n| Case | `message` |\n|---|---|\n| The body is not a JSON object sent as `application/json` | `Value, object or array expected.` |\n| A field is present but is not a string, or is empty | `Key <field> is not a string`, `Key <field> is empty string` |\n| `options` is not an object | `Key options is not an object` |\n| `options.dpi` or `options.authThreshold` is not an unsigned integer | `Key dpi is not an unsigned integer`, `Key authThreshold is not an unsigned integer` |\n| The body is an empty JSON object | `Empty payload` |\n| Neither `image1` nor `fingerTemplate1` is sent | `Missing required field: image1 or fingerTemplate1` |\n| Both `image1` and `fingerTemplate1` are sent | `Provide exactly one of image1 or fingerTemplate1` |\n| The side 1 value is not valid Base64 | `Malformed Base64 input` |\n| Neither `position1` nor `position` is sent | `Missing required field: position` |\n| The side 1 position is not one of the documented values | `Invalid finger position` |\n| Neither `image2` nor `fingerTemplate2` is sent | `Missing required field: image2 or fingerTemplate2` |\n| Both `image2` and `fingerTemplate2` are sent | `Provide exactly one of image2 or fingerTemplate2` |\n| The side 2 value is not valid Base64 | `Malformed Base64 input` |\n| Neither `position2` nor `position` is sent | `Missing required field: position` |\n| The side 2 position is not one of the documented values | `Invalid finger position` |\n| `options.dpi` is outside 250-1000 | `Invalid dpi value` |\n| `options.authThreshold` is greater than 100 | `Invalid authThreshold value` |\n\nProcessing errors (HTTP `400`):\n\n| `message` | Cause |\n|---|---|\n| `Finger verification failed` | The processing components could not compare the fingerprints |\n| `Invalid response from Engine` | The processing components returned a response the service cannot interpret |\n| `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` |\n| `Service not initialized`, `Service not configured` | The service is not ready yet |\n\nA `Negative` result is returned with HTTP `200`. Only successful authentications increase the usage counters\nand feed the quality figures of `GET /api/v1/finger/metrics`.\n","operationId":"authenticate","tags":["Finger Operations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticateRequest"}}}},"responses":{"200":{"description":"Public authentication response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticateResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFoundOnWorker"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```