minervaai-sdk

MinervaAI JavaScript SDK

The MinervaAI JavaScript SDK combines MinervaAI IDV and Search API functionality into one secure, harmonized interface. The JavaScript SDK is implemented on the client-side to accept a session token generated on the server-side and take end users through the ID Verification and AML Screening flow.

Full implementation of the SDK involves communication between 3 systems:

1. Your client-side, via a web browser or mobile application, built using a JavaScript framework such as React, Angular, Vue, Svelte, or React Native.
2. Your server-side, being the application running on your infrastructure that supports your client-side and handles your internal business logic.
3. The MinervaAI services, being the services running on the production MinervaAI cloud reached at https://api.minervaai.io and the IDV Onboarding Portal UI.

For more documentation, context, and example use cases, visit the MinervaAI Knowledge Hub

Web Token Authentication (JWT)

Server-Side

The SDK uses a temporary JavaScript web token (JWT) to authenticate requests from the end users on the client-side. This token must be generated first on the server-side by calling the sessions API, and then transmitted to the user's browser for frontend operations.

Ensure that you have been sent an invite to access the MinervaAI dashboard, where you will find your production server API key in the Account section. If you don't see a separate sandbox key assigned to your account, contact our support team ([e-mail]) to get access to one to enable sandbox features for integration in your non-production environments.

Use this API key on the MinervaAI client session POST endpoint from the server-side to generate a JWT at the point that it's needed for client-side authentication. Use the MinervaAI Web Sessions API, which is documented in the MinervaAI Knowledge Hub here.

At a high level, the server-side session API functionality is described below:

Usage:

POST https://api.minervaai.io/v1/web-sessions/client

Headers:

x-api-key: MINERVAAI_SERVER_API_KEY

Response body:

{
  "status": 200,
  "message": "Token generated successfully",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJJRF8iOiJmMTA4NzkxOS05OTQwLTQ1ZTctOTlmNi02YzIwYjBlZTJiNDUiLCJJc3N1ZWRfIjoiMjAyMy0wNC0yOVQyMzo0OTo1MC4yNzQyODMyNzRaIiwiRXhwaXJ5XyI6IjIwMjMtMDQtMzBUMDA6NDk6NTAuMjc0Mjc4NTQ5WiIsIlZhbGlkXyI6dHJ1ZSwiVXNlSG9zdGVkXyI6ZmFsc2UsIlNlc3Npb25JRF8iOiI2YTg0OGVmMC04ZGQwLTQ3ODAtYWY1Zi0yMTRmN2JjNDM4MWIiLCJleHAiOjE2ODI4MTU3OTB9._gnG-3pgMXKPQU9fZqvj9DjcP8L3PCYl4xAlhAmSYJo",
  "expires": "2023-04-30T00:49:50.274278549Z",
  "sessionId": "6a848ef0-8dd0-4780-af5f-214f7bc4381b"
}

The token in production mode is valid for 30 minutes, and should be generated just in time for SDK jobs requested from the client-side.

The sessionId should be captured on the server-side for future use, which can be used together with the server API key on the MinervaAI session data fetch API to get the results of the session data at any point in the future once the end user completes their IDV and screening flow.

Setup and configure the MinervaAI JavaScript Client SDK

Client-Side

Install the MinervaAI JavaScript SDK in a JavaScript-based project:

npm i minervaai-sdk

💡 If you are using the embedded flow with useHosted: true, you can intialize the ID verification flow embedded in a parent container instead of the default pop-up modal. To do this, provide the rootId parameter to the client constructor. To have the flow appear in a popup over everything on-screen, omit the rootId parameter.

When the MinervaAI customer verification processes are required, initialize the client with the value of token obtained from the call to the Create Web Session API:

import { initializeClient, launchVerification } from 'minervaai-sdk';

// Generate the client object
const client = initializeClient({
  token: TOKEN,
  rootId: 'custom-idv-frame-container',
  onComplete: () => {
    /** Custom completion event handler */
  },
  onCancel: () => {
    /** Custom cancellation event handler */
  },
  onError: (error) => {
    /** Custom error event handler */
  },
});

// Launch the client. Use the lifecycle callbacks to capture events
const { hostedUrl } = launchVerification(client);

Parameters

• token: (Required) Temporary JavaScript web token used to authenticate with the MinervaAI services.
• rootId: ID of the DOM element to use as a container to render the flow inside.

Obtain Full Data from a Completed Task Queue

Server-Side

Via the Web Session Fetch API

This API is best used to fetch data again at some point in the future. It shouldn't be used to get the data in real time as the end users are proceeding through the IDV flow. For real time data fetch, it is recommended instead to use the session data webhooks instead.

For more information about the data payloads of the IDV and screening components of the flow, please reference the Web Session Fetch API documentation in the MinervaAI Knowledge Hub. The anti-fraud and anti-money laundering flags and codes contained in the response payload are covered in more detail in the linked documentation.

Usage:

curl -X GET \
  -H 'x-api-key: MINERVAAI_API_KEY' \
  'https://api.minervaai.io/v1/web-sessions/server/:sessionid'

Headers:

x-api-key: MINERVAAI_SERVER_API_KEY

Response:

{
  "trackingId": "your-customer-guid",
  "status": "complete" | "pending" | "error",
  "code": "fail/input-mismatch",
  "sessionId": "6a848ef0-8dd0-4780-af5f-214f7bc4381b",
  "screening": {
    // Full fidelity screening data
  },
  "idv": {
    // Full fidelity IDV data
  }
}

SDK Error Codes

The SDK error codes are different from scan fail codes in that they represent a failure between the client- and server-side integration.

The error response body will return a status in the header, and a response message in the body as follows:

status code 400

The "name" parameter may not be more than 1024 characters in length.

Some error statuses may be as follows:

400 (Bad Request)
A 400 error may occur if the parameters included in the scan submission arguments are invalid, ill-formatted, or missing.

403 (Forbidden)
A 403 error may occur if server-side authentication of the web token fails due to an invalid token or expiry, if rate limits have been hit, or if volume quotas have far overrun.

404 (Not Found)
A 404 error may occur if the session of the JWT that is supplied to the end user does not exist in the database.

429 (Rate Limit) A rate limit of 5 requests per second is in place per IP. If the request rate exceeds this limit, then responses may be met with a 429 error.

500 (Internal Server Error)
An error has occured on the MinervaAI server-side.