@zauthy/sdk

Official JavaScript/TypeScript SDK for Zauthy — Auth, KYC, and Identity Verification.

Installation

npm install @zauthy/sdk

Quick Start

import { Zauthy } from '@zauthy/sdk'

const zauthy = new Zauthy({
  baseUrl: 'https://api.yourdomain.com',
  apiKey: 'sk_live_...',
})

// Sign up a user
const { access_token, user } = await zauthy.signup('[email protected]', 'password123', {
  fullName: 'John Doe',
})

// Set token for subsequent requests
zauthy.setAccessToken(access_token)

// Get current user
const profile = await zauthy.getCurrentUser()

Authentication

// Login
const tokens = await zauthy.login('[email protected]', 'password123')
zauthy.setAccessToken(tokens.access_token)

// Magic link
await zauthy.sendMagicLink('[email protected]')
const result = await zauthy.verifyMagicLink('token_from_email')

// OTP
await zauthy.sendOTP('[email protected]', 'email', 'login')
await zauthy.verifyOTP('[email protected]', '123456', 'login')

// OAuth
const { url } = await zauthy.initOAuth('google', 'https://yourapp.com/callback')
// Redirect user to url, then handle callback:
const authResult = await zauthy.handleOAuthCallback('google', code, state, redirectUri)

// MFA
const { secret, qr_code } = await zauthy.setupTOTP()
await zauthy.verifyTOTPSetup('123456')

// Password
await zauthy.forgotPassword('[email protected]')
await zauthy.resetPassword('reset_token', 'new_password')

// Logout
await zauthy.logout()

KYC Verification

// Full verification in one call
const result = await zauthy.verifyUser({
  externalUserId: 'user_123',
  document: documentFile,
  documentType: 'passport',
  selfie: selfieBlob,
  declaredAddress: '123 Main St, City',
})

console.log(result.overall_score) // 0-100
console.log(result.risk_level)    // 'low' | 'medium' | 'high'

// Or step by step
const session = await zauthy.createSession('user_123')
const doc = await zauthy.verifyDocument(session.id, documentFile, 'passport')
const face = await zauthy.matchFace(session.id, selfieBlob)
const liveness = await zauthy.checkLiveness(session.id, selfieBlob)
const final = await zauthy.completeVerification(session.id)

Webhooks

// Create a webhook
await zauthy.createWebhook('My Webhook', 'https://yourapp.com/webhook', ['user.signup', 'kyc.completed'])

// Express middleware for signature verification
import { verifyWebhookMiddleware } from '@zauthy/sdk'

app.post('/webhook', verifyWebhookMiddleware('whsec_...'), (req, res) => {
  console.log('Event:', req.body.type)
  res.json({ received: true })
})

Security

// Sessions & devices
const sessions = await zauthy.getUserSessions(userId)
await zauthy.revokeSession(userId, sessionId)

const devices = await zauthy.getUserDevices(userId)
await zauthy.trustDevice(userId, deviceId)

const summary = await zauthy.getSecuritySummary(userId)

Error Handling

import { Zauthy, ZauthyError } from '@zauthy/sdk'

try {
  await zauthy.login('[email protected]', 'wrong_password')
} catch (error) {
  if (error instanceof ZauthyError) {
    console.log(error.status)   // 401
    console.log(error.message)  // 'Invalid credentials'
    console.log(error.response) // Full API response
  }
}

License

MIT