Enroll (Face Capture)

There are two ways to initiate an enrollment through AwareID using Face Capture:

• QR code
  • a QR code is generated using a secondary application which is then scanned to receive
• Initiated via client
  • initiating the enrollment process via the client application entails making api calls yielding the information that would be present in QR code method and then continuing the enrollment process as normal from there.

On the enrollment is initiated then both methods follow the same steps.

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:

1. Retrieve an access token. This token allows communication between the client application and the AwareID servers.
2. Initiate an enrollment.
3. Add device
4. Enroll face

Enrollment Step 1 - Get Access Token

1. 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

1. 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
            }
        }
    }
}