Privacy Key 1:Few Search API

Privacy Key 1:Few Search allows to compare user biometric information to multiple Privacy Keys stored within authID platform using single API call.

As one of the use cases, it allows to compare biometric information of the user being onboarded via Proof to currently enrolled Privacy Keys.

Please see swagger reference documentation for details and please read Accessing the API section for prerequisites.

🚧

Role Requirements

The API Key needs Transaction Result Auditor and Configurator roles to run Privacy Key Search.

To access the search API in general the API Key also needs the Biometric Credentials Reader role.

Search API Endpoint

The Privacy Key search endpoint requires the following inputs:

• operationId: the Operation Id of a Proof or a Selfie transaction can be provided. The live user image information captured during Proof / Selfie transaction is used to search against existing Privacy Keys.

• accountNumbers(multiple allowed): the set of Accounts with existing Privacy Keys enrolled.

• numberOfBitsCorrection (optional): the accuracy-related parameter allowing for a measure of discrepancy between Privacy Key and incoming facial image information. When omitted, the tenant-level default is used.

Sample API Call

curl -X 'POST' \
  'https://id.authid.ai/search/search' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer <Authid Token>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'operationId=d363b7e9-804c-d13f-4834-da0e3f884924' \
  -F 'accountNumbers=AccountOne' \
  -F 'accountNumbers=AccountTwo' \
  -F 'accountNumbers=AccountThree' \
  -F 'accountNumbers=AccountFour' \
  -F 'numberOfBitsCorrection=2'

API Response

The search returns the list of records, providing the data for each Account specified in accountNumbers list.

An example of response with one unique record is shown below:

{
  "matches": [
    {
      "score": 0,
      "pbPublicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAX3aMZiPqtmAvNA1cL03nCpp2YP5qXXlq7TpUuIU+/tg=\n-----END PUBLIC KEY-----\n",
      "pbSignatureType": "EdDSA",
      "pbAttestationData": "eyJTZWFyY2hJRCI6ImNmZjI5Y2E5LTk3ZDQtNzllZS1lMWJjLTlhYjFmMWMwZWY4ZiJ9",
      "pbAttestationSignature": "LZvxFeDAfidVAM7UH9pQfKBgq3XrH4PXSKOkRVhLSUMUK2FYfheWodYsFMAO0Pt7sAnGAlU1ETxUYlRfxjbUDQ==",
      "id": "emZhY3siVGltZSI6IjIwMjUtMDYtMTBUMTM6NTA6NTguNTYzOTU0MSswMDowMCJ9",
      "owner": {
        "id": "061dcd09-5cee-425f-b5c3-ab4382dbd8b3",
        "name": "AccountOne"
      },
      "modifiedDate": "2025-06-10T14:28:00.567",
      "deletedDate": null
    }
  ],
  "warnings": [
    {
      "message": "Account 'AccountOne' has no enrolled privacy keys.",
      "accountPrivacyKeysNotFound": {
        "account": {
          "id": "809fc710-355c-4e8b-8a6a-ef2e207b2b7d",
          "name": "AccountTwo"
        }
      }
    },
    {
      "message": "No account found for account number 'AccountThree'.",
      "accountNotFound": {
        "account": {
          "id": null,
          "name": "AccountThree"
        }
      }
    }
  ]
}

Successfull Match

matches array contains information about the Privacy Keys that matched the user. Each array element is described below:

owner.id contains the unique identifier (UIN) of the user account the Privacy Key credential belongs to

owner.name contains the accountNumber attribute of the account.

id contains the Credential Id attribute of the specific Privacy Key that matched.

pbPublicKey contains the Public Key corresponding to Privacy Key private key.

Matching Not Performed

warnings array contains information indicating that comparison of the Privacy Key was not done for some of the provided Accounts, together with the corresponding reason:

• account does not exist
• account exists, but has no associated Privacy Keys

No Match Found

If the Privacy Key for the given accountNumber provided in the input does not match the biometric information of the user, nothing is reported for that accountNumber.

In an example where all Account Numbers listed as a input have Privacy Keys, but none of it produces a match, the output would contain empty array as no matches or warnings are generated.