SDKs

The Checktiv Web SDK (@checktiv/sdk-web) lets you embed identity verification directly in your own app. The client surface is two lines: Checktiv.init(...) to configure the SDK, then .mountProvisioned(...) to render the verification experience. A complete integration also requires roughly four backend touchpoints: minting a session via the public API, minting a bt_* browser token, verifying webhook signatures on your server, and registering your publishable-key origin.

What the SDK gives you

• Managed IDV module - camera capture, liveness detection, and document scan rendered inside your page. The verification journey runs in a sandboxed iframe; your page never touches the raw capture data.
• Consent-gated fraud module - passive signal collection that starts only after the applicant grants consent.
• React wrapper - <ChecktivJourney> for a zero-lifecycle embed, plus <ChecktivProvider> and <ChecktivIdv>, for React and Next.js apps.
• White-label theming - set primaryColor at init() time; the journey inherits your brand color. Brand your own page layout around the SDK embed for logos.

Install

Via npm:

npm install @checktiv/sdk-web

Via CDN script tag (IIFE, no bundler required):

<script src="https://sdk.us.checktiv.com/v1/sdk.js" crossorigin="anonymous"></script>

This loads the latest release automatically. After the script tag loads, the SDK is available as window.Checktiv.

For production deployments, pin to a specific version and include a Subresource Integrity hash to guard against CDN compromise. SRI is only coherent on the immutable pinned URL, not the moving /v1/sdk.js pointer. See Versioning for the pinned URL shape and how to derive the SRI hash.

The two-line client surface

const client = Checktiv.init({
  publishableKey: 'ah_pk_us_test_...',
  getSessionToken: async (ctx) => {
    const res = await fetch('/api/checktiv/token', { method: 'POST' });
    return (await res.json()).token;
  },
});

client.mountProvisioned({ target: document.getElementById('idv-container') });

init() never contacts a network; mountProvisioned() fetches the server-declared session modules and renders them. The secret key used to mint the session stays on your server.

Backend touchpoints

Before the SDK renders, your backend must:

1. Create a session via POST /v1/sessions with your secret key (ah_sk_...). See the API reference.
2. Mint a browser token (bt_*) via POST /v1/sessions/:id/browser_token. The SDK calls getSessionToken whenever it needs a fresh token.
3. Register allowed origins for your publishable key so the SDK can load on your domain. See API keys.
4. Receive the verdict via webhook. The checktiv.idv.submitted event on the SDK signals capture is complete; the authoritative outcome arrives on your server as a kyc.session.* webhook. See Verdict and webhooks.

Guides

Get started

• Quickstart - end-to-end integration walkthrough
• Sample app - a minimal, runnable Express + HTML own-page example

Core concepts

• Token handoff - how a verification is created and how the bt_* browser token is issued
• Security headers - the Permissions-Policy and CSP entries your page needs before the camera can open
• Modules overview - the full public surface and how each subpath is registered

Features

• React - ChecktivProvider and <ChecktivIdv>
• Custom forms - render author-defined intake fields in the journey
• Credit history - render the credit-history step and handle every outcome it can produce
• Collect user info - satisfy a collect_user_info step from your own form before the journey
• Cross-device handoff - let a desktop applicant continue on their phone
• Advanced capture - build a custom capture renderer on the Tier-1 / Tier-2 core
• Theming - apply your brand color to the verification journey
• Workspace reviewer - embed the hosted review workspace in your own product
• Fraud consent - consent gating for the fraud signal module
• Verdict and webhooks - receive the outcome securely via signed webhook

Reference and operations

• Error reference - every error code with its cause and recovery step
• Versioning - pinning, the compatibility window, and the evolution contract
• Secret key rotation - rotate or revoke ah_sk_* safely
• Release notes - release history for @checktiv/sdk-web
• AI agent steering - rules and recipes for AI coding agents integrating the SDK

REST API

You can also use the REST API directly without the SDK. See the API reference and the REST quickstart.