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:

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