Enroll

Estimated reading: 6 minutes 945 views

There are two methods of enrolling a user with AwareID. The first method involves using a separate web based application to generate a QR for a client to scan using their mobile device and then initiate an enrollment. The second method involves starting the enrollment on the client device.

Web Portal

To start an enrollment using the QR code method we must first generate the QR code to be consumed by the client application (in our example we use a web app). This web application uses a UI to allow an enduser to register using a username and email address. Then uses these pieces of information in the API Call for /triggerEnroll.

www.awareid.aware-apis.com

Trigger Enroll

We initiate an enrollment by calling the /triggerEnroll endpoint with our received access token

  • username - required
  • email - required
  • notifyOptions - optional
POST baseUrl + /b2c/proxy/triggerEnroll
Content-Type: 'application/json; charset=UTF-8',

{ "username": "[email protected]",

    "email": "[email protected]",

    "notifyOptions": {

        "notifyByEmail": false  

    }
}

Response - Trigger Enroll

STATUS CODE 200

{
status : "SUCCESS"
sessionCallbackURL : "<https://awareid-dev.aware-apis.com/onboarding?data=jgTW40dmoG6Hp_d6Rg7YaZ97vfGSlV5BcBJvLvqXVmhoQ2Hg2DcC2Kvr9AkTZ38ZkyIfiSj80QFxOWs1YeckYsp3D0D9vS46wppl1Zdt-tpiAdzlvBKA2DBfcj7rf0VePWUn1vKdIPgEoWAulqRxZ_mNakFB7FijLg0QJ8kYsB6w0Nk1A4m9QtLGIdHcuGn9XJnxooQHyr2yhtUsgfOo2FrRXYmFIF7ZNwxYd56miFCs-yuD6eZZcvZ1M01Wje7ji0NYUWVpdes-DA_P0cKgsLPX5sV7SyPSlf9kmoCQz7Ag20kAKkOf-LFFKQmgnJ3362nXIEovxS8vp4BCClu7vIfEVCE2s1zS7zNwrDuRfFdViVAQMMxDMe77LnbKbfvLqUhiv--wPFyV9Iier1EDSL9y5kikOw_PGSyuRzvbQKuoNdGj-IqVZYZ_5QivOFqq_OEt8jaX1zZxAiQ8uXRt3g>"
qrcodeImage : "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"
sessionToken : "aa73e547-0f1b-4235-a7b0-dd52fa4ab774"
errorSummary : null
}

Our response for trigger enroll includes five pieces of information with the most relevant piece being the base64 encoded string of the QR that is used to be displayed to the user to continue the enrollment on their device.

Screenshot 2023-01-25 at 1.07.36 PM.png

2. Enrollment Process & Endpoints

Base URL

www.awareid.aware-apis.com/b2c

To perform a successful enroll using the Voice SDK and AwareID we need to follow 4 simple steps.

These steps include:

  1. Scan QR code and decrypt data
  2. Initiate an enrollment.
  3. Add device
  4. Enroll voice

The QR Code will return a url with an encrypted data parameter named “data”.

This data has to be decrypted using the available public key. Once decoded 3 pieces of information are provided separated by “&”.

  1. Host url
    1. this URL is where all subsequent api calls will be made through
  2. The API Key
    1. this API Key is used in the header of api calls
    2. the key value pair in the header is as follows:
    <aside> 💡 “apikey”:API_Key</aside>
  3. Session Token
    1. the session token is used to validate the session.

1. Validate Session Token

The first api call necessary is to enroll a user is /tokenVerify/validateSession

POST /tokenVerify/validateSession
"Content-Type": 'application/json; charset=UTF-8',
"apikey": apiKey

{
	"sessionToken":sessionToken
}

Response - Validate Session Token

{
    "accessToken": "accessToken",
    "methodType": "enroll",
    "customerName": "customerName",
    "customerLogo": "",
    "userName": "customerUsername",
    "email": "customerEmail"
}

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",
        "addVoice"
    ]
}

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> 💡 ANDROID This device ID can be retrieved using the following code:Settings.Secure.getString(getContentResolver(), Settings.Secure.ANDROID_ID);

</aside>

<aside> 💡 iOS This device ID can be retrieved using the following code:UIDevice.current.identifierForVendor!.uuidString

</aside>

POST /onboarding/enrollment/adddevice
Authorization: 'Bearer AccessToken'
apikey: 'apikey'

{
    "enrollmentToken": "enrollmentToken",
    "deviceId": "deviceID"
}

Response for add device

{
    "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 voice sample and check if sample belongs to a live person

The add voice API call requires the json package generated by the Voice SDK (you will need to capture 3 voice samples for enrollment for use with this endpoint). 

POST /onboarding/enrollment/addVoice
Content-Type: 'application/json; charset=UTF-8',
Authorization: 'Bearer AccessToken'

{
    "enrollmentToken": "{{enrollment_token}}",
    "livenessData": {
        "voice": {
            "voiceSamples": [
                {"data": {{LiveVoiceSample1}},},
                {"data": {{LiveVoiceSample2}},},
                {"data": {{LiveVoiceSample3}},}
            ],
            "workflow": {{workFlowName}},
        }
    }
}

Response for add voice 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
  • Liveness Result
    • Broken down into several fields giving feedback on the liveness score
STATUS CODE 200
{
    "livenessResult": true,
    "enrollmentStatus": 2,
    "registrationCode": "LLXL2N",
    "livenessResults": {
        "voice": {
            "liveness_result": {
                "decision": "LIVE",
                "feedback": [],
                "score_frr": 1.1757098732441127
            }
        }
    }
}

CONTENTS

Powered By Aware Inc