Verify

Overview

Getting started

Quickstart

Verify Quickstart Guide

This guide walks you through the set up process of a basic Verify integration.

A full sample implementation is available on GitHub and includes both client and server side code.

Set up a Hive account

If you haven't already signed up for a Hive account, you can do so here - it's free. We recommend that you log in to follow this quickstart.

Implementation steps

Step 1: Obtain Your Keys::Dashboard

You can get the keys from the Developers section in the Dashboard. You will need the following:

  1. Application Key
  2. API Key
  3. API Secret

applications

keys

Step 2: Install the SDK::Client

You will need the SDK to integrate Verify into your web application. You can either install the library locally in your application or load it from our CDN.

From CDN

html
012345678
<html>
  <head>
    ...
    <script src='https://cdn.hive.id/verify-js/2.1.0/verify.js'></script>
  </head>
  <body>
    ...
  </body>
</html>

Module bundlers

terminal
01234
# Installation with npm
npm install --save @hiveid/verify-js


# Installation with yarn
yarn add @hiveid/verify-js

Step 3: Create a customer::Server

On your backend, create a Customer object using the API.

curl
0123
$ curl https://api.hive.id/customers \
  -H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \
  -d email="john@hive.id" \
  -X POST

Depending on your use case, we recommend that you create the customer in Hive together with your application’s user account. You should also store the customer identifier in your database for future reference.

Example customer response:

response
0123456789101112
{
  "id": "8462e8ce-4245-4eca-835c-4a160b93b030",
  "email": "john@hive.id",
  "phone": null,
  "first_name": null,
  "middle_name": null,
  "last_name": null,
  "gender": null,
  "dob": null,
  "metadata": {},
  "created_at": 1602241760,
  "updated_at": 1602241760
}

Step 4: Create a session::Server

On your backend, create a Session using the API to obtain the session_token, which will be used in the next step. You will need your Application Key from Step 1.

Session tokens are restricted to an individual customer and expire after 90 minutes. We recommend that you create exactly one session for each submission attempt.

curl
01234
$ curl https://api.hive.id/sessions \
  -H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \
  -d customer_id="8462e8ce-4245-4eca-835c-4a160b93b030" \
  -d application_key="hWsqWCs7fS4nfKW1cYevw7fxKLKTN78a" \
  -X POST

Example session response:

response
012
{
  "session_token": "eyJhbGciOiJIUzI1N...cEOjL8vBlkCD2TlUvp1qzGNs"
}

Step 5: Add the SDK::Client

Include the Verify.js SDK on a page where you would like your customers to start verifying their identity. You will need to pass the applicationKey (Application Key from Step 1) and the sessionToken (Session token from Step 4).

HTML + JS

html + js
01234567891011121314151617181920212223242526272829303132333435
<html>
  ...
  <body>
    <button id="verification-btn">Start verification</button>
    <div id="verification-container"></div>
    <script>
      document.addEventListener("DOMContentLoaded", () => {
        const Verify = window.hiveid.Verify;
        const verificationBtn = document.getElementById("verification-btn");
        const verificationContainer = document.getElementById(
          "verification-container"
        );
        Verify.configure(applicationKey, {
          language: "en",
          languageSelector: true,
          mode: "modal",
          theme: {
            primaryColor: "#6E37D8",
            secondaryColor: "#DFCFF8",
            buttonPrimaryHover: "#5426AB",
            buttonPrimaryText: "#ffffff",
            QRCodeColor: "#000000",
          },
        });
        const handleVerificationCompleted = (payload) => {};
        const handleVerificationCanceled = () => {};
        const handleButtonClick = async () => {
          Verify.mount(verificationContainer, sessionToken);
        };
        Verify.on("completed", handleVerificationCompleted);
        Verify.on("canceled", handleVerificationCanceled);
        verificationBtn.addEventListener("click", handleButtonClick);
      });
    </script>
  </body>
</html>

React

react
01234567891011121314151617181920212223242526272829303132333435363738394041424344
import React, { useEffect, useRef } from "react";


Verify.configure(applicationKey, {
  language: "en",
  languageSelector: true,
  mode: "modal",
  theme: {
    primaryColor: "#6E37D8",
    secondaryColor: "#DFCFF8",
    buttonPrimaryHover: "#5426AB",
    buttonPrimaryText: "#ffffff",
    QRCodeColor: "#000000",
  },
});
export function App() {
  const containerRef = useRef(null);
  useEffect(() => {
    const verificationCompletedUnsubscribe = Verify.on(
      "completed",
      handleVerificationCompleted
    );
    const verificationCanceledUnsubscribe = Verify.on(
      "canceled",
      handleVerificationCanceled
    );
    return () => {
      verificationCompletedUnsubscribe();
      verificationCanceledUnsubscribe();
    };
  }, []);
  const handleVerificationStarted = async () => {
    if (!containerRef.current) {
      return;
    }
    Verify.mount(containerRef.current, sessionToken);
  };
  const handleVerificationCompleted = (payload) => {};
  const handleVerificationCanceled = () => {};
  return (
    <div>
      <button onClick={handleVerificationStarted}>Start verification</button>
      <div ref={containerRef} />
    </div>
  );
}

Step 6: Create a check::Server

As the last step in the verification flow, once the customer session is completed, you will need to initiate a Check from your backend using the API.

curl
0123
$ curl https://api.hive.id/checks \
  -H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \
  -d session_id="d8779205-f122-4325-af25-942e7850b696" \
  -X POST

Example response:

response
012345678
{
  "id": "db3590ce-3121-4b0d-9839-733709727f7b",
  "session_id": "d8779205-f122-4325-af25-942e7850b696",
  "status": "processing",
  "decision": null,
  "report": null,
  "created_at": 1602251909,
  "updated_at": 1602251909
}
HomeVerifyAPI ReferenceGitHubTwitter