Biometric API endpoints

Prerequisites

Configure the SecureAuth® Identity Platform to use "Biometric identification," enable the API for a SecureAuth Identity Platform realm, and configure a request header. See the Authentication API guide.

GET /factors

Use the GET /factors method to access the end user's profile and generate a biometric response.

The factors are returned if you use /api/v2 and the user status in Active Directory matches one of the following:

InvalidGroup
Disabled
Lockout
PasswordExpired
AccountExpired

HTTP Method	URI	Example	SecureAuth product
GET	`/api/v2/users/<username>/factors`	https://secureauth.company.com/api/v2/users/jsmith/factors	version 19.07 or later

POST /auth

The POST method validates the end user biometric response.

HTTP Method	URI	Example	SecureAuth product
POST	`/api/v2/auth`	https://secureauth.company.com/api/v2/auth	version 19.07 or later

Request POST payload

Request payload parameters

{
    "user_id": "<USERNAME>",
    "type": "push_accept_biometric",
    "factor_id":"<DEVICE IDENTIFIER>",
    "biometricType":"fingerprint",
      "push_accept_details": {
        "company_name": "<COMPANY>",
        "application_description": "<APPLICATION>",
        "enduser_ip": "<IP ADDRESS>"
    }

}

Request payload example

{
    "user_id": "jsmith",
    "type": "push_accept_biometric",
    "factor_id":"dc3ceaf4180c417eb7bfd573f75fb796",
    "biometricType":"fingerprint",
      "push_accept_details": {
        "company_name": "ACME Corp",
        "application_description": "Salesforce",
        "enduser_ip": "123.123.123.123"
    }

}

Response payload

GET /auth

Combine the GET /auth method and the reference ID to contact the endpoint to validate if the end user has accepted the request.

HTTP Method	URI	Example	SecureAuth product
GET	`/api/v2/auth/<reference_id>`	https://secureauth.company.com/api/v2/auth/5523d444-e92e-4297-ae27-fbc6cb3288b3	version 19.07 or later

Response example

{
    GET /auth/5523d444-e92e-4297-ae27-fbc6cb3288b3
}

Return example

{
    "status": "found",
    "message": "ACCEPTED",
}

Definitions

status: Status with one of the matching outcomes:

found: Fingerprint or face found with acceptable match_score
not_found: Fingerprint or face not found and returned a message stating: User ID was not found. This could occur, for example, if the fingerprint or face was set up on a public computer. The fingerprint or face would not be saved so it would not be found.
invalid: Fingerprint or face found, but with unacceptable match_score and returned a message stating: User ID is not associated with a valid fingerprint or face.
message: Additional information regarding the status: PENDING, ACCEPTED, DENIED, EXPIRED, FAILED, NOTFOUND, WRONG, Invalid Reference ID