Embed Verification in Your App

Use @tokenive/connect to embed credential verification directly in your web application. Users complete verification in a modal without leaving your site.

Install

npm install @tokenive/connect

How It Works

Quick Start

1. Create a proof request (backend)

Your server creates a verification request using your API key:

import { Tokenive } from '@tokenive/sdk';

const tokenive = new Tokenive({
  apiKey: process.env.TOKENIVE_API_KEY,
  baseUrl: process.env.TOKENIVE_BASE_URL,
});

// Create a request for your customer
const request = await tokenive.proofRequests.create({
  requester_entity: 'Your Company',
  proof_type_id: 'proof_of_address',
  customer_email: 'customer@example.com',
});

// Return request.id to your frontend

2. Open Connect (frontend)

import { open } from '@tokenive/connect';

const handler = open({
  requestId: 'request-id-from-backend',
  onSuccess: (result) => {
    // Verification complete!
    console.log('Credential ID:', result.credentialId);
    console.log('Shared at:', result.sharedAt);
  },
  onClose: () => {
    // User dismissed the modal
  },
  onError: (error) => {
    console.error(error.code, error.message);
  },
});

That's it. The modal handles authentication, provider selection, and verification. Your backend can poll the proof request status to confirm.

3. Confirm verification (backend)

const status = await tokenive.proofRequests.get(requestId);

if (status.status === 'verified') {
  // Customer's credential has been verified and shared with you
}

API Reference

open(options): ConnectHandler

Opens the verification modal.

Option	Type	Required	Description
requestId	string	Yes	Proof request ID from your backend
onSuccess	(result) => void	Yes	Called when verification completes
onClose	() => void	No	Called when user dismisses modal
onError	(error) => void	No	Called on errors
portalUrl	string	No	Override portal URL (for testing)

ConnectResult

{
  credentialId: string;  // The verified credential ID
  sharedAt: string;      // ISO timestamp when shared
}

ConnectError

{
  code: 'expired' | 'email_mismatch' | 'network' | 'unknown';
  message: string;
}

ConnectHandler

{
  close: () => void;  // Programmatically close the modal
}

Full Example

Express Backend

import express from 'express';
import { Tokenive } from '@tokenive/sdk';

const app = express();
app.use(express.json());

const tokenive = new Tokenive({
  apiKey: process.env.TOKENIVE_API_KEY,
  baseUrl: process.env.TOKENIVE_BASE_URL,
});

app.post('/api/verify', async (req, res) => {
  const { email, proofType } = req.body;

  const request = await tokenive.proofRequests.create({
    requester_entity: 'My Company',
    proof_type_id: proofType || 'proof_of_address',
    customer_email: email,
  });

  res.json({ requestId: request.id });
});

app.get('/api/verify/:id/status', async (req, res) => {
  const request = await tokenive.proofRequests.get(req.params.id);
  res.json({ status: request.status });
});

HTML Frontend

<script type="module">
  import { open } from '@tokenive/connect';

  document.getElementById('verify-btn').addEventListener('click', async () => {
    // 1. Create request on your backend
    const res = await fetch('/api/verify', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email: 'customer@example.com',
        proofType: 'proof_of_address',
      }),
    });
    const { requestId } = await res.json();

    // 2. Open the verification modal
    open({
      requestId,
      onSuccess: (result) => {
        alert(`Verified! Credential: ${result.credentialId}`);
      },
      onClose: () => {
        console.log('User closed');
      },
    });
  });
</script>

Mobile Apps

For React Native or other mobile frameworks, open the verification URL in a WebView:

https://portal.tokenive.io/verify/{requestId}?embed=true

Listen for postMessage events to detect completion:

// Message format
{ type: 'tokenive:success', payload: { credentialId, sharedAt } }
{ type: 'tokenive:close' }
{ type: 'tokenive:error', payload: { code, message } }

Testing

Use the demo app to test the full flow locally:

cd examples/connect-demo
cp .env.example .env  # Add your API key
npm start             # http://localhost:4000

Next Steps

• Error handling guide — handle edge cases
• API Reference — full endpoint documentation