Introduction

In this tutorial we will not implement anything, but instead, we will go through the identification process and we will use curl to call the Authenteq API. We strongly recommend following this tutorial before you jump to the integration explained in the guide "How to integrate Web SDK?".

Before we start, please prepare your ID. It can be a passport, national identity document or driving license. You should also have client_id and client_secret you can get from the Customer Dashboard.

Direct User to Authenteq Identity Server

Use the following command to start the Web SDK to request identity verification session. Put in your client_id and client_secret and make sure that the redirect_uri matches with the URI defined in the Customer Dashboard.

curl --user <client_id>:<client_secret> \
     --location --request POST 'https://api.app.authenteq.com/oauth/request_verification' \
     --data-urlencode 'redirect_uri=https://example.com/redirect' \
     --data-urlencode 'state=randomrandom'
     
{"verificationUrl":"https://web-idv.app.authenteq.com/verify?token=<token>"}

Open the above link in your browser.

User Performs Identification

Follow the steps of the identification (introduction, liveness check, document scan, redirect). Your user will go through the same process. Continue upon the successful redirect.

You should have been redirected to:

<redirect_uri>?code=...&state=...

Getting the Code

Now the user was redirected back to your service. With that redirect, we send back the code in a parameter.

Go to the address bar of your browser and copy the value of the code parameter.

You may notice that it is not the only parameter. The other one is the state, which is the random string we sent earlier. You may wonder why to send the same value back and forth? It is to make sure, that it is your service that initiated the identification process. Once you generate state you should save its value in a session or a cookie. When your service receives redirect it should compare value received with the saved state and ignore the code if the values don't match. This check is optional but also highly recommended.

Exchanging Code for a Token

Once you have a code you can exchange it for an access_token, which you will use to authorize the request to retrieve the user details.

curl --user <client_id>:<client_secret> \
     --location --request POST 'https://api.app.authenteq.com/oauth/token' \
     --data-urlencode 'grant_type=authorization_code' \
     --data-urlencode 'redirect_uri=https://example.com/redirect' \
     --data-urlencode 'code=<code>'

Execute the command above with the code you got earlier and put values to client_id, client_secret and redirect_uri . Copy the access_token from the response.

Why do we need to exchange the code for the token? Couldn't we just use code to authorize future requests? The answer is: we could, but the exchange gives an extra layer of protection. It requires a secret that is only known by you. So even if an attacker would intercept the code, he won't be able to do anything with it. The secret must be kept secret, so the exchange must happen in the backend of your service.

Retrieving Results

Now you have everything to retrieve user data. Let's call /verifications/result endpoint. We need to place the access_token in the Authorization header with a prefix Bearer.

$ curl --location --request GET 'https://api.app.authenteq.com/verifications/result' \
       --header 'Authorization: Bearer <access_token>'
{
  "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=="
    }
  }
}

Execute above curl with the proper access_token and we are done! User details reached your system.