How to Integrate Web IDV?

Steps

Confirming a user's identity with Authenteq Web IDV is fairly simple. You can integrate our solution into your system with four basic steps.

1) Get your client details

Once you sign up, we will create a client account for your system. You will get from us:

  • client_id - an identifier that you will use to authorize requests. You will pass that openly in the URL parameters

  • client_secret - an alphanumeric string that you will use for token exchange and retrieving user details

Use the Customer Dashboard to set:

  • redirect_uri - the URI that your user is redirected to on successful identity verification. The link must be an HTTPS link. (i.e: https://example.com/success)

2) Create the "Sign Up with Authenteq" Button

To initialize the identity process request verification using https://api.app.authenteq.com/oauth/request_verification. You will receive link to Authenteq Identity Server. By following the link, the user will begin the identification process:

  • liveness test

  • ID scan,

  • identity verification - where we verify that the person who performed the liveness test is the document holder.

To inform the user that their identity will be verified using an external service you could use our button:

Sign Up with Authenteq button.

Here are the HTML and CSS for the button:

button.html
button.css
button.html
<a class="AuthenteqButton" href="https://web-idv.app.authenteq.com/verify?token=<token>">
<img class="AuthenteqButton-logo" src="authenteq-logo.png" alt="Authenteq Logo" />
<div class="AuthenteqButton-caption">Sign Up with Authenteq</div>
</a>
button.css
.AuthenteqButton,
.AuthenteqButton:hover,
.AuthenteqButton:active {
margin: 0 auto;
display: block;
position: relative;
height: 48.59px;
width: 286px;
border-radius: 28px;
background-color: #F29E2E;
box-shadow: 0 5px 10px -5px rgba(0,0,0,0.2);
color: #FFFFFF;
font-family: Roboto;
font-size: 15px;
line-height: 18px;
text-align: center;
}
.AuthenteqButton-logo {
display: block;
width: 30px;
height: 30px;
position: absolute;
top: 9px;
left: 16px;
}
.AuthenteqButton-caption {
position: absolute;
top: 9px;
left: 62px;
height: 30px;
width: 224px;
color: #FFFFFF;
font-family: Roboto;
font-size: 15px;
line-height: 30px;
font-weight: 100;
text-align: center;
border-left: 1px solid #FFFFFF;
}

Please use this file to display our logo:

3) Exchange code for the token

When the identify verification process is complete, we will redirect the user to the redirect URI and add two parameters:

  • code - the code that you will use to retrieve the authorization token,

  • state - the random string you passed when you initialized the verification session.

Before you proceed with the token exchange, verify that the state value equals the value you set in the link to the Authenteq Identity Server. You can do that by comparing it with the state value saved in the cookie or session.

To exchange the token, you will have to perform a POST request to https://api.app.authenteq.com/oauth/token and provide the following parameters:

  • grant_type - indicates token exchange. Its value should be authorization_code,

  • code - the code passed to redirect_uri in the query parameters,

  • redirect_uri - the redirect URI that was used to receive the code,

You will authorize the request with Basic Auth using client_id and client_secret:

The response will be a JSON object:

{
"access_token": "...",
"token_type": "bearer",
"expires_in": 86399,
"scope": "read write",
"jti": "..."
}

This request should be performed in the backend of your service.

You may ask why we don't send the token immediately. The code use to retrieve the authorization token is sent as a URL parameter, and usually stored in server logs. If we pass the token immediately, the valuable security information would be stored in server logs, which are usually not the most protected resource.

Once the code is exchanged for the token you can no longer use it, so the value stored in the server logs becomes useless.

However, the main reason is that you need to provide your secret to retrieve the token. This way we can make sure that even if someone intercepted the code, using, for example, a malicious browser plugin, it would be impossible to use the code to hijack the data transfer to access user details.

4) Get user details

You can get the details by performing GET request to: https://api.app.authenteq.com/verifications/result

To authorize the request, you must pass the token in the Authorization header of your request:

Authorization: Bearer <token>

The endpoint will return the user details:

{
"id": "3631324b-5bcc-48b0-b717-4f12f45e0a1d",
"status": "PASSED",
"platform": "WEB",
"startTime": "2020-04-10T11:44:40.644143+07:00",
"documentData": {
"documentType": "DL",
"documentNumber": "1234567890",
"issuingCountry": "USA",
"jurisdiction": "Uta",
"nationality": "USA",
"firstName": "JOHN",
"lastName": "DOE",
"nameSuffixes": "Mr",
"namePrefixes": "Jr",
"sex": "M",
"dateOfBirth": "1964-12-30",
"dateOfExpiry": "2022-12-30",
"dateOfIssue": "2012-05-30",
"licenseClass": "B/C/D",
"licenseClassDetails": {
"B": {
"from": "2019-01-30",
"to": "2029-01-30",
"notes": "Some valuable note"
},
"C": {
"from": "2019-01-30",
"to": "2029-01-30"
},
"D": {
"from": "2019-01-30",
"to": "2029-01-30"
}
},
"croppedFrontImage": {
"contentType": "image/jpeg",
"content": "Y3JvcHBlZEZyb250SW1hZ2U="
},
"croppedBackImage": {
"contentType": "image/jpeg",
"content": "Y3JvcHBlZEJhY2tJbWFnZQ=="
}
}
}

Once you have a token, you have 15 minutes to retrieve the user details. After that time, the token expires and you no longer can access the data.