How to Integrate Web SDK?

Steps

Confirming a user's identity with Authenteq Web KYC with OAuth 2.0 flow 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:

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

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

To create the account we will need the following information:

  • redirectUri - 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)

  • logo - your company logo that will be displayed on top of the page during the identity check

2) Create the "Sign Up with Authenteq" Button

To initialize the identity process you must redirect your users to our Identity Server using the following link:

https://identity.authenteq.com/authorize

The URL must contain the following parameters:

  • response_type - indicates the type of OAuth flow. Currently, we only support a code flow, so the value should be code

  • client_id - the client identifier provided to you

  • redirect_uri - the URI where we will redirect users on successful identity verification. To prevent possible fraud, it must match the URI defined in your account

  • scope - a list of user properties you want to get from user details. Currently, the only supported value is kyc

  • state - a random string generated by your application that you can use to verify that the redirect that comes to your website is from the identification process started by your website. You can store the state value in the cookie and verify that it matches the value that arrived in the redirect

  • back_url - the URL for the Back to ... link in the identity server (optional)

By following the link, https://identity.authenteq.com/authorize, 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 should use our custom 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://identity.authenteq.com/oauth?response_type=<...>&client_id=<...>&redirect_uri=<...>&scope=<...>&state=<...>&back=<...>">
<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 in the link to the Authenteq Identity Server

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.authenteq.com/v2/web-kyc/token and provide the following parameters:

  • grantType - indicates token exchange. Its value should be authorizationCode

  • code - the code passed to redirectUri in the parameters

  • redirectUri - the redirect URI that was used to receive the code

  • clientId - your client Id

  • clientSecret - your secret

The response will be a JSON object:

{
"token": "fa3243fsd...",
}

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.authenteq.com/v2/web-kyc/details

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:

{
portrait: "<base64_encoded_JPEG_image>",
selfie: "<base64_encoded_JPEG_image>",
croppedDocs: {
front: "<base64_encoded_JPEG_image>",
back: "<base64_encoded_JPEG_image>",
},
details:
{
documentNumber: "8136431812",
issuingCountry: "DEU",
documentType: "FG617451",
givenNames: "ANNA MARIA",
surname: "SCHMIDT",
dateOfBirth: "1987-01-12",
nationality: "DEU",
dateOfIssue: "2017-01-30",
dateOfExpiry: "2027-01-30",
sex: "F"
}
}

5) Anti-Money Laundering (AML) Check

Clients using the aml scope will also receive details about possible matches to the user details in JSON output:

{
"content": {
"data": {
"id": 46,
"ref": "1495711341-Tu51KL9s",
"searcher_id": 1,
"assignee_id": 1,
"search_profile": {
"name": "My USA Profile 1",
"slug": "my-usa-profile-1"
},
"filters": {
"entity_type": "person",
"types": [
"sanction",
"warning"
],
"birth_year": "1924",
"passport": "AD10095",
"exact_match": false,
"fuzziness": 0.6
},
"match_status": "potential_match",
"risk_level": "unknown",
"search_term": "Robert Mugabe",
"total_hits": 1,
"updated_at": "2015-06-18 16:52:42",
"created_at": "2015-06-18 16:52:42",
"tags": {
"name": "value"
},
"hits": [
{
"doc": {
"aka": [
],
"associates": [
{
"name":"Grace Mugabe",
"association":"Spouse"
}
],
"entity_type": "person",
"fields": [
{
"locale":"en",
"name":"Justification",
"source":"swiss-seco-list",
"value":"Head of Government and responsible for activities that seriously undermine democracy, respect for human rights and the rule of law."
},
{
"name":"Other Information",
"source":"swiss-seco-list",
"value":"President."
},
{
"name":"Date of Birth",
"source":"swiss-seco-list",
"tag":"date_of_birth",
"value":"1924"
}
],
"first_name": "Robert",
"id": "RU4326M8GFUAHMF",
"last_name": "Mugabe",
"last_updated_utc": "2015-06-16T01:11:14Z",
"middle_names": "Gabriel",
"media": [
{
"date": "2015-10-08T00:00:00Z",
"pdf_url": "http://complyadvantage- pdf.s3.amazonaws.com/255949c2-7ff4-482e-a2d6-03904e2b7986.pdf",
"snippet": "Zimbabweans are struggling with inflation of more than 100,000 percent",
"title": "Zimbabwe court to rule on election results | Reuters",
"url": "http://www.reuters.com/article/2008/04/14/ us-zimbabwe-election-idUSL0457212820080414"
}
],
"name": "Mugabe Robert Gabriel",
"sources": [
"swiss-seco-list"
],
"types": [
"sanction"
]
},
"is_whitelisted": false,
"match_types": [
"name_exact",
"year_of_birth"
],
"score": 3.511
}
],
"share_url": "http://app.complyadvantage.com/public/search/ 1496748100-l9qHqbVF/64a6114f299b"
}
},
"status": "success"
}

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.