Authentikare SDK

What's the Authentikare SDK?

The Authentikare SDK for JavaScript is a client-side library that allows you to integrate the Authentikare verification process into your website. The SDK provides a simple and secure way to verify the identity of your users, ensuring that they are who they claim to be.

Two types of verification are available:

• LiveCAPTCHA: A simple and secure way to verify the identity of your users, ensuring that they are who they claim to be.
• AuthentiCheck: A more advanced verification process that includes additional checks such as age verification.

Getting Started

Step 1: Integration process initiation.

To initiate the integration process and obtain a valid session_id, the external website needs to make a server-to-server call to the following endpoint:

POST https://mytenant.authentikare.com/app/api/v1/create-session

Request Parameters (JSON):

• <string> credentials (required): The credentials necessary to authenticate the request and ensure the security of the process.
• <string> external_id (required): An identifier unique to the external website or user initiating the integration process. This identifier will be associated with the generated session_id.
• <string> webhook (required): Endpoint of the external website to send back the results.
• <string> phone (optional).
• <string> type (required): Type of verification ([liveness|id-check])
• <array[string]> scopes (optional): What type of information is needed. [known values: over_18]

LiveCAPTCHA Verification example.

curl --location 'https://mytenant.authentikare.com/app/api/v1/create-session' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_id": "a20cf480-c657-4c41-8630-3e97097a56d3",
    "webhook": "https://some.external.website.domain.com/",
    "phone": "+12345657999",
    "type": "liveness",
    "credentials": "secret"
  }'

AuthentiCheck Verification example.

curl --location 'https://mytenant.authentikare.com/app/api/v1/create-session' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_id": "a20cf480-c657-4c41-8630-3e97097a56d3",
    "webhook": "https://some.external.website.domain.com/",
    "phone": "+12345657999",
    "type": "id-check",
    "scopes": ["over_18"],
    "credentials": "secret"
  }'

Response:

{
  "data": {
    "session_id": ""
  }
}

The response includes the following property:session_id. A valid session_id serves as a signature for subsequent interactions during the integration process. The external website needs to securely store this session_id for further use.

Error Response in case of invalid credentials:

{
  "error": {
    "message": "invalid credentials",
    "status": 401
  }
}

In case of an error, the server will respond with an appropriate HTTP status code and an error message in the response body, allowing the external website to handle the error accordingly.

Step 2: Initialization.

To initialize the Authentikare SDK, the external website needs to include the following script tag in the head section of the HTML file:

<script type="text/javascript" src="https://mytenant.authentikare.com/app/websdk.js"></script>

The external website also needs to include the following link tag in the head section of the HTML file:

<link href="https://mytenant.authentikare.com/app/static/css/websdk.css" media="" rel="stylesheet" type="text/css">

Step 3: Start the process.

To start the process, the external website needs to call the following function:

<script type="text/javascript">
    Authentikare.init(session_id, {
        onComplete: () => void, // When the process completes or the Authentikare modal closes
        onSessionInvalid: () => void, // When the session does not exist or is invalid
        appType: "liveness" | "id-check",
        language: "fr"|"en"
    });
</script>

Make sure to replace session_id with the actual value you received from the backend during the initialisation process.

The function will open a modal window with the Authentikare SDK for JavaScript, allowing the user to complete the verification process.

Step 4: Handle the result.

Once the verification process has been completed, our system will send the results back to the external website using a webhook, a backend-to-backend communication that allows to deliver the outcome of the process.

Verification Succeed

In the case of a successful verification, Authentikare will send an HTTP POST request to the specified webhook URL of the external website. The request will include the following information in the request body:

{
  "data": {
    "session_id": "788743f0-f355-4bea-9a85-68ff36804ef1",
    "external_id": "aaaaa",
    "status": "succeed",
    "details": {
      // if scope was requested
      "over_18": true|false
    },
    "notify_via_sms": true
  }
}

The details field contains an object of the traits that have been verified successfully, such as age, gender, hair color, and visible tattoos. The notify_via_sms field represents the Boolean value of the phone toggle.

Verification Declined:

If the verification process is declined for any reason, Authentikare will send an HTTP POST request to the webhook URL with the following payload:

 {
  "data": {
    "session_id": "788743f0-f355-4bea-9a85-68ff36804ef1",
    "external_id": "aaaaa",
    "status": "declined",
    "reason": ["instructions_not_followed", "underage"],
    "notify_via_sms": false
  }
}

The reason field contains an array of reasons indicating why the verification was declined, such as "instructions not followed," "under age," or "low quality video/audio." The notify_via_sms field represents the Boolean value of the phone toggle.

Contact us.

We appreciate your interest in our app. In case of feedback our questions contact us at: [email protected] .

---

Updated on 24/11/2023