Authentication Workflow
When an end user you have already onboarded returns to your platform, use Jumio Authentication to verify they are the same person. Jumio Authentication captures a new selfie and compares it to the existing reference selfie already associated with the user’s account.
Typically, the reference selfie is the one collected during the initial onboarding process using the Identification Document and Identity and Selfie Verification workflow.
Depending on your organization’s data retention policy (see Data Settings), the reference selfie is:
Stored on Jumio’s servers and associated with the user’s account if it is still within the configured retention period.
Deleted from Jumio’s servers if it is beyond the retention period. In that case, if you wish to run authentication, you must have stored the reference selfie on your own servers and upload it before performing authentication with the new selfie.
When someone claiming to be an end-user you have already onboarded returns to your platform, use Jumio Authentication to make sure they really are the same person. Jumio Authentication captures a fresh Selfie and Facemap and compares them to an existing Facemap that is already associated with the end-user account.
Typically the existing Facemap is the one that was acquired when the end user was first onboarded using the Identification Document and Identity Verification (IDIV) Workflow. Depending on your organization's Data Retention policy (See Data Settings) that Facemap is:
- Stored on Jumio's servers, and associated with the accountClosed if it is within the configured Data retention period.
- Facemap data is deleted from Jumio's servers once it exceeds the configured data retention period. Please note that with Jumio Liveness, it is no longer possible to download and store facemap data.
You must record and retain the account ID generated by the on-boarding transaction. The account ID value can be obtained from the Portal or from the API responses. For additional information see Creating or Updating Accounts.
When you have an existing end user account with an existing Facemap, the process to authenticate the same user is as follows:
- Update the Account to Initiate an Authentication Transaction
- Complete the Customer Journey for the Authentication Transaction
- Retrieve the Decision
Update the Account to Initiate an Authentication Transaction
Use the PUT request for the Accounts API to update the existing end user account. The account ID value saved from the on-boarding transaction is used as a path parameter in the request URL.
In the request body, specify workflow key 10014 to use the standard Authorization workflow.
Workflow 10014 uses the Authentication capability to compare a newly-acquired Facemap to the existing Facemap. If you require a custom workflow with additional services or risk signals contact your Jumio representative.
Example Request Body
{
"customerInternalReference":"transaction_1234",
"workflowDefinition":{
"key": 10014
}
}
Providing the End-User Consent
If your integration uses one of the Mobile SDKs with a custom user interface you can use the original consent obtained when the end user was onboarded instead of requiring the end user to provide an explicit consent for each authentication transaction. In this case you must have recorded the timestamp from the onboarding, and be able to use it to set the userConsent values, as shown in the example below. The original consent can be valid for a maximum of 3 years. Beyond that the end user must explicitly provide the consent, as described here.
{
"customerInternalReference":"transaction_1234",
"workflowDefinition":{
"key": 10014
},
"userConsent":
"consent": {
"obtained": "yes",
"obtainedAt": "2022-07-20T17:20:35.000Z"
}
}
}
Complete the Customer Journey for the Authentication Transaction
Authentication requires your integration to use either the Web Client or one of the Mobile SDKs. A new Facemap is required, which cannot be uploaded through the REST APIs. See Credential Acquisition for additional information.
The end user is guided to take the new Selfie and Facemap. When they have been successfully uploaded the workflow is finalized.
Retrieve the Decision
If your integration has a callback service it will be notified when the transaction is complete. Alternatively you can call the Transaction Status API to determine if the transaction has been PROCESSED.
Once the transaction has completed you can call the Workflow Details API to retrieve the decision and other workflow data.
Example Details Response
{
"workflow": {
"id": "UUID",
"status": "PROCESSED",
"definitionKey": "10014",
"customerInternalReference": "transaction_1234"
},
"account": {
"id": "UUID"
},
"createdAt": "2023-04-19T17:54:28.218Z",
"startedAt": "2023-04-19T17:55:15.170Z",
"completedAt": "2023-04-19T17:55:16.126Z",
"credentials": [
{
"id": "UUID",
"category": "SELFIE",
"parts": [
{
"classifier": "FACE",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/c4daab5f-bbe7-4fea-8d0e-1e6a9fa0094a/parts/FACE"
}
]
},
{
"id": "UUID",
"category": "FACEMAP",
"parts": [
{
"classifier": "FACEMAP"
},
{
"classifier": "LIVENESS_1",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_1"
},
{
"classifier": "LIVENESS_3",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_3"
},
{
"classifier": "LIVENESS_2",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_2"
},
{
"classifier": "LIVENESS_5",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_5"
},
{
"classifier": "LIVENESS_4",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_4"
},
{
"classifier": "LIVENESS_6",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_6"
}
]
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "PASSED"
},
"risk": {
"score": 0.0
}
},
"steps": {
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/workflow-executions/a6692412-a1e1-4fbc-a3fa-79c210af25b6/steps"
},
"capabilities": {
"usability": [
{
"id": "UUID",
"credentials": [
{
"id": "UUID",
"category": "SELFIE"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
}
},
{
"id": "UUID",
"credentials": [
{
"id": "UUID",
"category": "FACEMAP"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
}
}
],
"authentication": [
{
"id": "UUID",
"validFaceMapForAuthentication": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/FACEMAP",
"credentials": [
{
"id": "UUID",
"category": "FACEMAP"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
},
"data": {
"type": "JUMIO_STANDARD"
}
}
]
}
}