Auther Embedded

The Kit usage

Auther Embedded Kit is designed for verifying the liveness of persons who are subject to subsequent biometric authentication using face recognition technology.

The main Kit element is an Intel RealSense depth camera, which allows you to determine the volume of a face before checking its biometric data. This way allows you to prevent illegal use of biometric identity data by third parties and to fights fraud and stop spoofing attacks involving photos, cut-outs, and videos.

The device has a flexible API right out of the box and is highly customizable for different business cases.

This Kit can be used in real cases where there is a need to perform a liveness check in order to open an e-gates or identify an identity in a mobile kiosk, self-checkout, POS or ATM.

Liveness integration overview

Demonstration of the integration of Auther Embedded liveness with NeoFace Watch - a face recognition engine from the world leader NEC. The speed of checking the liveliness and identification in the amount of about half a second.

System requirements

During the launch, the device has to be connected to the internet to check its license.

Auther Live software is only compatible with several Intel RealSense cameras and AAEON single-board computers. What you need to install our software:

Face requirements

The device will successfully capture the face and check it for liveness if the following requirements are met:

Auther Liveness license activation

Software designed to check the liveness of a person's face using the Intel RealSense camera. Running on the AAEON Up-board computer. Follow the step-by-step instructions to activate the license and get the installation script:

1. Register Account on the https://app.auther.ai website.

2. Log into your Account.

3. Go to the License section and press "Add license" button.

4. Choose "I have activation code" and provide your activation code if required; if your account already includes licenses, proceed.

5. Setup license grants.

Depending on the grants which were added to the license on License tab, single-board computer may fulfill the following requests in Auther Check API:

6. Special [installation command] is generated now. Copy software installation command from the license line, which will be later used for software installation on the Up-Board single-board computer.

Auther Liveness software installation

To install the software, you must first install the Ubuntu server on the Up-board computer. Follow the step by step instructions below to successfully complete the licensing process for your single-board computer:

Auther Liveness software configuration.

After you have completed the installation, you can make additional configuration of the application by going to the config file /etc/riddleboard/config.ini
The default settings of functions that are available for configuration:

Auther CHECK API v6.0.0

API description

Auther Embedded has a local API and already contains integration with the Auther Check API to work with biometric authentication functions directly through the device.

Overview

This page describes the technical requirements that must be met to start using facial recognition technology in your applications and products. Please read all the sections in detail and strictly follow the requirements specified in the documentation and your integration will go quickly and smoothly. Sign-up and get a free plan for testing!

Quick start guide

To send your first request, follow the steps below. For faster and more convenient testing, we recommend using Postman. Sign-up and get the API Key to authorize your requests.

Glossary

List of terms that are used in requests and responses:

Image requirements

The input image as base64-encoded bytes is required. For successful preparation of the Bade64-encoded image, before you sent requests, follow to the next criteria:

Image verification criteria

To successfully create a person_id, the image of the person you submit for enrollment will be verified for compliance with the following criteria:

Requests

All API requests must be sent in JSON format with the header:

Key
Content-Type
Api-Key
Value
application/json
api_key
Content-Type: application/json
Api-Key: api_key

{  
   "code": "F_001",   
   "type": "string",  
   "message": "string"
}

Authorization

Every request sent must be authenticated using the API Key. It should be sent in an HTTP header. You can create and manage your API Keys in the back-office. To get the API Key, you need to Sign-up and get a free plan for testing.

Required credentials

api_key

Base URL

http://localhost:8080

Request headers

Key
Api-key
Value
api_key

Response headers

Key
Request-Id
Value
request_id

Get face image

Get a face that is in front of the camera or was less than 1 second ago. As a result, you will receive liveness verified Base64 encoded image with 120x120 pixels resolution that meets the requirements above.

URL:
GET
/person/face/

Request headers

Go to request headers

Request Body

Parameter
no parameter
Type
no type
Request body


Response headers

Go to response headers

Status code 200

Parameter
faceKey
faceImage
Type
string
string
200 Ok

{
  "faceKey":"string",
  "faceImage": "string”
}

Status code 400

Parameter
code
message
Type
string
string
400 Bad Request

{
   "code": "string",
   "message": "string"
}

Codes and messages for response 400

Codes
R_400
R_404
Messages
“Сamera is not connected”
“Face not found / face didn't pass liveness check"

Create person

To register a person in the system, please submit a Base64-encoded image of a a person on where the person looks straight ahead and also prepare the person_id you want to assign to this person in advance. When preparing the reference image, follow the requirements described above in the Image requirements section. Download "faceImage" sample.

URL:
POST
/person/face/{person_id}

Request headers

Go to request headers

Request Body

Parameter
faceImage
Type
string
Request body

{
  "faceImage": "string"
}

Response headers

Go to response headers

Status code 200

Parameter
created
personId
updated
Type
string
string
string
200 Ok

{
"personId": "string",
"created": "2020-09-03T16:05:08.938Z",
"updated": "2020-09-04T16:05:08.938Z"
}

Status code 400

Parameter
code
message
Type
string
string
400 Bad Request

{
   "code": "string",
   "message": "string"
}

Codes and messages for response 400

Codes
F_012
F_011
F_010
F_009
F_008
F_007
F_006
F_005
F_004
F_003
F_002
F_001
CP_002
R_002
R_003
Messages
“Face exists”
“Wrong face size when image check"
“Wrong face yaw”
“Wrong face pitch”
“Wrong face roll”
“Sharpness is bad”
“Brightness is bad”
“Sunglasses exists”
“Mouth is open”
“Eyes are closed”
“Most likely face doesn’t exist”
“Should be one face”
“Customer profile already exists with id %s”
“Request body exception”
“Fields validation exception”

Status codes: 401, 403, 500

Update person

To update the data of a person in the system, please submit a Base64-encoded image of a a person on where the person looks straight ahead and also indicate the person_id of the person you want to assign new data to.
For preparing the reference image, follow the requirements described above in the Image requirements section.

URL:
PUT
/person/face/{person_id}

Request headers

Go to request headers

Request Body

Parameter
faceImage
Type
string
Request body

{
  "faceImage": "base64format_string"
}

Response headers

Go to response headers

Status code 200

Parameter
created
personId
updated
Type
string
string
string
200 Ok

{
"personId": "string",
"created": "2020-09-03T16:05:08.938Z",
"updated": "2020-09-04T16:05:08.938Z"
}

Status code 400

Parameter
code
message
Type
string
string
400 Bad request

{
   "code": "string",
   "message": "string"
}

Codes and messages for response 400

Codes
F_012
F_011
F_010
F_009
F_008
F_007
F_006
F_005
F_004
F_003
F_002
F_001
CP_002
R_002
R_003
Messages
“Face exists”
“Wrong face size when image check"
“Wrong face yaw”
“Wrong face pitch”
“Wrong face roll”
“Sharpness is bad”
“Brightness is bad”
“Sunglasses exists”
“Mouth is open”
“Eyes are closed”
“Most likely face doesn’t exist”
“Should be one face”
“Customer profile already exists with id %s”
“Request body exception”
“Fields validation exception”

HTTP Status code: 404

Parameter
code
message
Type
string
string
404 Bad request

{
   "code": "NF_001",
   "message": "Face not found in collection"
}

Codes and messages for response 404

Codes
NF_001
Messages
“Face not found in collection”

HTTP Status code: 401, 403, 500

Remove person

To remove a person's data from the system, just send the person_id parameter. The person's data will be deleted and the person_id will also be deleted.

URL:
DELETE
/person/face/{person_id}

Request headers

Go to request headers

Request Body

no parameters

Response headers

Go to response headers

HTTP Status code: 200

200 Ok

‍

HTTP Status code: 400

Parameter
code
message
Type
string
string
400 Bad request

{
   "code": "string",
   "message": "string"
}

Codes and messages for response 400

Codes
R_002
R_003
CP_005
Messages
“Request body exception”
“Fields validation exception”
“Number of available requests exceeded”

HTTP Status code: 404

Parameter
code
message
Type
string
string
404 Bad request

{
   "code": "NF_001",
   "message": "Face not found in collection"

Codes and messages for response 404

Codes
NF_001
Messages
“Face not found in collection”

HTTP Status codes: 401, 403, 500

Get person by id [beta]

To check if the person_id already exist in the system, just specify the path with person_id . If the person_id exist in response you will get the same person_id and information when person was created and updated.

URL:
GET
/person/face/{person_id}

Request headers

Go to request headers

Request Body

no parameters

Response headers

Go to response headers

HTTP Status code: 200

200 Ok

{
"personId": "string",
"created": "2020-09-03T16:05:08.938Z",
"updated": "2020-09-04T16:05:08.938Z"
}

HTTP Status code: 400

Parameter
code
message
Type
string
string
400 Bad request

{
   "code": "string",
   "message": "string"
}

Codes and messages for response 400

Codes
R_002
R_003
CP_005
Messages
“Request body exception”
“Fields validation exception”
“Number of available requests exceeded”

HTTP Status code: 404

Parameter
code
message
Type
string
string
404 Bad request

{
   "code": "NF_001",
   "message": "Face not found in collection"

Codes and messages for response 404

Codes
NF_001
Messages
“Face not found in collection”

HTTP Status codes: 401, 403, 500

Identify person

Submit the Base64-encoded image. With this request, we start 1:N searching for the most similar enrolled person in our system. The search result will be person_id, which matches the searched one by 98%.
To improve the quality and speed of recognition, follow the image requirements for the submitted images. Download "faceImage" sample.

URL:
POST
/person/recognize-face

Request headers

Go to request headers

Request Body

Parameter
faceImage
Type
string
Request body

{
 "faceImage": "string"
}

Response headers

Go to response headers

HTTP Status code: 200

Parameter
created
personId
updated
Type
string
string
string
200 Ok

{
"personId": "string",
"created": "2020-09-03T16:05:08.938Z",
"updated": "2020-09-04T16:05:08.938Z"
}

HTTP Status code: 400

Parameter
code
message
Type
string
string
400 Bad request

{
   "code": "string",
   "message": "string"
}

Codes and messages for response 400

Codes
R_002
R_003
F_011
CP_005
Messages
“Request body exception”
“Fields validation exception”
“Wrong face size when image check”
“Number of available requests exceeded”

HTTP Status code: 410

Parameter
code
message
Type
string
string
410 No person matched

{
   "code": "string",
   "message": "string"
}

Codes and messages for response 410

Codes
RF_001
Messages
“No person matched”

HTTP Status codes: 401, 403, 500

Verify person [beta]

Comparison of the face of a person who declares that his face belongs to the known person_id. With this request, we start 1:1 matching for the enrolled person in our system. If the submitted person's face matches to 80% with the person's image that belongs to the declared person_id, then the verification result is successful.

URL:
POST
/person/verify-face/{person_id}

Request headers

Go to request headers

Request Body

Parameter
faceImage
Type
string
Request body

{
 "faceImage": "string"
}

Response headers

Go to response headers

HTTP Status code: 200

Parameter
personId
created
updated
Type
string
string
string
200 Ok

{
"personId": "string",
"created": "2020-09-03T16:05:08.938Z",
"updated": "2020-09-04T16:05:08.938Z"
}

HTTP Status code: 400

Parameter
code
message
Type
string
string
400 Bad request

{
   "code": "R_002",
   "message": "Request body exception"
}

Codes and messages for response 400

Codes
R_002
R_003
CP_005
Messages
“Request body exception”
“Fields validation exception”
“Number of available requests exceeded”
200 Ok

{
"personId": "string",
"created": "2020-09-03T16:05:08.938Z",
"updated": "2020-09-04T16:05:08.938Z"
}

HTTP Status code: 404

Parameter
code
message
Type
string
string
404 Bad request

{
   "code": "R_002",
   "message": "Request body exception"
}

Codes and messages for response 404

Codes
NF_001
Messages
“Face not found in collection”

HTTP Status codes: 401, 403, 500

Compare person [beta]

Compares the face on the sourceImage with the largest face detected on the targetImage.
By default, the submitted sourceImage will be compared the targetImage with the 80% of similarity threshold. If you want to compare images with a custom similarity threshold (for example, 98%), specify this number in the request body [option]. In response, you get the value of the similarity images.

URL:
POST
/person/compare-face

Request headers

Go to request headers

Request Body

Parameter
targetImage
sourcetImage
Type
string
string
Request body

{
"targetImage": "string",
"sourceImage": "string"
}

Request Body [option]

Parameter
targetImage
sourceImage
similarityThreshold
Type
string
string
number
Request body

{
"targetImage": "string",
"sourceImage": "string",
"similarityThreshold": number
}

Response headers

Go to response headers

HTTP Status code: 200

Parameter
similarity
Type
value
200 Ok

{
"similarity": value
}

HTTP Status code: 400

Parameter
code
message
Type
string
string
400 Bad request

{
   "code": "R_002",
   "message": "Request body exception"
}

Codes and messages for response 400

Codes
R_002
R_003
CP_005
Messages
“Request body exception”
“Fields validation exception”
“Number of available requests exceeded”

HTTP Status codes: 401, 403, 500

Response status codes

The custom 200 and 400 response codes are listed in the description for each request. Common server response codes are listed below.

HTTP Status code: 200

Parameter
personId
created
updated
Type
string
string
string
200 Ok

{
"personId": "string",
"created": "2020-09-03T16:05:08.938Z",
"updated": "2020-09-04T16:05:08.938Z"
}

HTTP Status code: 400

Parameter
code
message
Type
string
string
400 Bad request

{
 "code": "string",
 "message": "string"
}

HTTP Status code: 401

Parameter
code
message
Type
string
string
401 Unauthorized

{
 "code": "string",
 "message": "string"
}

HTTP Status code: 403

Parameter
code
message
Type
string
string
403 Forbidden

{
 "code": "string",
 "message": "string"
}

HTTP Status code: 404

Parameter
code
message
Type
string
string
404 Face not found

{
 "code": "string",
 "message": "string"
}

HTTP Status code: 500

Parameter
code
message
Type
string
string
500 Internal Server Error

{
 "code": "string",
 "message": "string"
}

Have a question or wanna share your ideas?

Go to Help Center