Enroll (Face Capture)
Initiate enrollment from client
Base URL
www.awareid.aware-apis.com
To perform a successful enroll using the Face SDK and AwareID we need to follow 4 simple steps.
These steps include:
- Retrieve an access token. This token allows communication between the client application and the AwareID servers.
- Initiate an enrollment.
- Add device
- Enroll face
Enrollment Step 1 - Get Access Token
- Our first step is to retrieve an “access_token”. This token will be used in our next api call to retrieve an enrollment token to proceed with enrollment.
POST /auth/realms/{{customer_name}}-consumers/protocol/openid-connect/token
Content-Type: 'application/x-www-form-urlencoded',
"client_id": client_id
"client_secret": client_secret
"scope": openid
"grant_type" : client_credentials
<aside> This is the only call whose content type of this call is “application/x-www-form-urlencoded”
</aside>
Response for openid-connect
STATUS CODE 200
{
"access_token": {{ACCESS_TOKEN}},
"expires_in": {{TIME_IN_SECONDS}},
"refresh_expires_in": 0,
"token_type": "Bearer",
"id_token": {{JWT_TOKEN}},
"not-before-policy": 0,
"scope": "openid"
}
Enrollment Step 2 - Initiate An Enrollment
- With the method type we start onboarding with accessToken, sessionToken, apikey
POST /onboarding/enrollment/enroll
Authorization: 'Bearer AccessToken'
apikey: 'apikey'
{
"username": "username",
"firstName": "first name", //optional
"lastName": "last name" //optional
"email": "user email",
"phoneNumber": "user phonenumber"
}
Response for openid-connect
STATUS CODE 200
{
"enrollmentToken": "enrollmentToken",
"userExistsAlready": false,
"requiredChecks": [
"addDevice",
"addFace"
]
}
Enrollment Step 3 - Add device
The device ID is checked when performing an authentication to confirm the device enrolled is the same as the device attempting.
<aside> This device ID can be retrieved using the following code:
Settings.Secure.getString(getContentResolver(), Settings.Secure.ANDROID_ID);
</aside>
POST /onboarding/enrollment/adddevice
Authorization: 'Bearer AccessToken'
apikey: 'apikey'
{
"enrollmentToken": "enrollmentToken",
"deviceId": "deviceID"
}
Response for add device
STATUS CODE 200
{
"enrollmentStatus": 1,
"registrationCode": ""
}
From here the response will include a registration code and enrollment status.
There are 3 enrollment statuses:
- 0 = Enrollment Failed
- 1 = Enrollment Pending
- 2 = Enrollment Complete
Enrollment Step 4 - Add face sample and check if sample belongs to a live person
The add face API call requires the json package generated by the Face SDK.
POST /onboarding/enrollment/addFace
Authorization: 'Bearer AccessToken'
apikey: 'apikey'
{
"enrollmentToken": enrollmentToken,
"faceLivenessData": {"iv": iv, "key": key, "p": p}
}
Response for add face sample
The response from the enrollment call returns:
- Liveness Result
- This is a boolean value.
- returns true if the sample is assessed to be a live sample
- returns false is the sample is assessed to not be live
- Enrollment Status
- 0 = failed
- 1 = pending
- 2 = success
- Registration Code
- this code is used in the re-enrollment process
- Face Liveness Result
- Broken down into several fields giving feedback on the liveness score
STATUS CODE 200
{
"livenessResult": true,
"enrollmentStatus": 2,
"registrationCode": "LLXL2N",
"faceLivenessResults": {
"video": {
"liveness_result": {
"decision": "LIVE",
"feedback": [],
"score_frr": 1.1757098732441127
}
}
}
}