Back to Home

SDK Reference

Complete documentation of the Veiled JavaScript SDK

VeiledClient

Main class for interacting with the Veiled API

Constructor

new VeiledClient(config: VeiledConfig)

Parameters:

  • apiKeyrequired

    Your API key obtained from the dashboard

  • apiUrloptional

    API URL (default: https://verify.veiled.id/api/v1)

  • localeoptional

    Interface language: 'it-IT' | 'en-US' (default: 'it-IT')

  • debugoptional

    Enable debug logging (default: false)

Methods

isVerified()

Check if the user is already verified

async isVerified(): Promise<IsVerifiedResult>

Returns:

{
  verified: boolean;
  token?: string;
  userId?: string;
}

verify()

Start the age verification process

async verify(options?: VerifyOptions): Promise<VerifyResult>

Options:

  • provider

    Verification provider: 'yoti' | 'namirial'

  • returnUrl

    Return URL after verification (default: current page)

  • mode

    Mode: 'redirect' | 'popup' (default: 'redirect')

  • onSuccess

    Callback called after successful verification

  • onError

    Callback called on error

getStatus()

Get current verification status

getStatus(): { verified: boolean; token?: string }

clear()

Remove current verification (logout)

clear(): void

🆕 QR Verification Methods

New QR code verification methods (v2.0+)

showQRVerification()

Show a modal with QR code for mobile verification. The method automatically handles status polling and final confirmation.

async showQRVerification(options?: QRSessionOptions): Promise<void>

Options:

  • returnUrl

    Return URL (default: current page)

  • onScanned

    Callback called when QR is scanned

  • onCompleted

    Callback called after verification completed (receives JWT token)

  • onError

    Callback called on error

  • onTimeout

    Callback called if session expires

  • onCancel

    Callback called if user closes the modal

verifyDirect()

Direct verification on mobile/desktop without QR code. Automatically detects device type.

async verifyDirect(options?: { returnUrl?: string }): Promise<void>

createQRSession()

Create a QR session manually (for custom implementations).

async createQRSession(returnUrl?: string): Promise<SessionCreateResult>

Returns:

{
  sessionId: string;
  qrCodeUrl: string;
  qrCodeDataUrl: string;
  expiresAt: string;
}

checkQRStatus()

Check the status of a QR session.

async checkQRStatus(sessionId: string): Promise<SessionStatusResult>

Returns:

{
  status: 'waiting_for_scan' | 'scanned' | 'pending_confirmation' | 'completed' | 'expired' | 'failed';
  ready: boolean;
  expiresAt: string;
}

confirmQRSession()

Confirm a QR session and retrieve the JWT token.

async confirmQRSession(sessionId: string): Promise<SessionConfirmResult>

Returns:

{
  success: boolean;
  token?: string;
  userId?: string;
  error?: string;
  message?: string;
}

handleDirectReturn()

Handle return from direct verification, extracting the token from URL.

async handleDirectReturn(): Promise<{ success: boolean; token?: string }>

Examples

Basic Verification

const veiled = new Veiled.VeiledClient({
  apiKey: 'pk_live_your_key'
});

const { verified } = await veiled.isVerified();
if (!verified) {
  await veiled.verify();
}

🆕 QR Verification (Desktop → Mobile)

const veiled = new Veiled.VeiledClient({
  apiKey: 'pk_live_your_key'
});

// Mostra QR code per verifica mobile
await veiled.showQRVerification({
  onScanned: () => {
    console.log('📱 QR scansionato!');
  },
  onCompleted: (token) => {
    console.log('✅ Verifica completata!', token);
    unlockContent();
  },
  onError: (error) => {
    console.error('❌ Errore:', error);
  }
});

🆕 Direct Verification (Mobile/Desktop)

const veiled = new Veiled.VeiledClient({
  apiKey: 'pk_live_your_key'
});

// Su mobile o desktop: verifica diretta senza QR
await veiled.verifyDirect({
  returnUrl: 'https://yoursite.com/callback'
});

// Sulla pagina di callback:
const { success, token } = await veiled.handleDirectReturn();
if (success) {
  console.log('Token salvato!', token);
  unlockContent();
}

🆕 Custom QR Implementation

const veiled = new Veiled.VeiledClient({
  apiKey: 'pk_live_your_key'
});

// 1. Crea sessione QR
const session = await veiled.createQRSession();
console.log('Session ID:', session.sessionId);
console.log('QR URL:', session.qrCodeUrl);

// 2. Mostra QR code nella tua UI custom
displayQRCode(session.qrCodeUrl);

// 3. Polling status
const checkStatus = setInterval(async () => {
  const status = await veiled.checkQRStatus(session.sessionId);

  if (status.ready) {
    clearInterval(checkStatus);
    enableConfirmButton();
  }

  if (status.status === 'expired') {
    clearInterval(checkStatus);
    showError('Sessione scaduta');
  }
}, 3000);

// 4. Conferma quando utente clicca
confirmButton.addEventListener('click', async () => {
  const result = await veiled.confirmQRSession(session.sessionId);

  if (result.success) {
    console.log('Token:', result.token);
    unlockContent();
  }
});

With Callbacks

await veiled.verify({
  onSuccess: (token) => {
    console.log('Verificato!', token);
    showProtectedContent();
  },
  onError: (error) => {
    console.error('Errore:', error);
    showErrorMessage();
  }
});

With Debug

const veiled = new Veiled.VeiledClient({
  apiKey: 'pk_live_your_key',
  debug: true // Abilita log console
});