Node.js SDK

Coming Soon TypeScript-first Node.js 18+

Coming Soon — The Node.js SDK is under development. In the meantime, you can use the REST API directly with a single fetch call.

The Node.js SDK (@xident/node) provides a TypeScript-first client for server-side token verification, usage queries, and webhook handling. It works with Node.js 18+, Deno, and Bun.

Installation

npm install @xident/node

Quick Start

import { XidentClient } from '@xident/node';

const xident = new XidentClient({
  secretKey: process.env.XIDENT_SECRET_KEY  // sk_live_xxx
});

// Verify a token from the callback
const result = await xident.verificationTokens.verify('tok_xxx');

if (result.verified) {
  console.log('Age bracket:', result.age_bracket);  // 18
  console.log('Session:', result.session_id);
}

Express.js Example

import express from 'express';
import { XidentClient } from '@xident/node';

const app = express();
const xident = new XidentClient({
  secretKey: process.env.XIDENT_SECRET_KEY
});

// Handle the verification callback
app.get('/verified', async (req, res) => {
  const { token, status } = req.query;

  if (status !== 'success' || !token) {
    return res.redirect('/verification-cancelled');
  }

  try {
    const result = await xident.verificationTokens.verify(token as string);

    if (result.verified && result.age_bracket >= 18) {
      // Store verification in session
      req.session.ageVerified = true;
      req.session.ageBracket = result.age_bracket;
      return res.redirect('/content');
    }

    return res.redirect('/too-young');
  } catch (error) {
    console.error('Verification failed:', error);
    return res.redirect('/verification-error');
  }
});

Planned API Surface

const xident = new XidentClient({ secretKey: 'sk_live_xxx' });

// Token verification
await xident.verificationTokens.verify(token);
await xident.verificationTokens.issue({ account_id, age_bracket, tenant_id });
await xident.verificationTokens.revoke(token);

// Usage & billing
await xident.usage.get({ from: '2026-01-01', to: '2026-01-31' });

// Webhook signature verification
const isValid = xident.webhooks.verifySignature(payload, signature, secret);

TypeScript Types

interface VerificationResult {
  verified: boolean;
  age_bracket: number;        // 12, 15, 18, 21, or 25
  session_id: string;
  user_id?: string;           // If passed via StartOptions
  metadata?: Record<string, string>;
  verified_at: string;        // ISO 8601 timestamp
}

interface XidentClientOptions {
  secretKey: string;          // sk_live_xxx or sk_test_xxx
  baseUrl?: string;           // Default: https://api.xident.io
  timeout?: number;           // Request timeout in ms (default: 10000)
}

Error Handling

import { XidentClient, XidentError } from '@xident/node';

try {
  const result = await xident.verificationTokens.verify(token);
} catch (error) {
  if (error instanceof XidentError) {
    console.log(error.code);     // 'TOKEN_EXPIRED', 'TOKEN_USED', 'INVALID_TOKEN'
    console.log(error.message);  // Human-readable message
    console.log(error.status);   // HTTP status code (400, 401, 404, etc.)
  }
}

Using the REST API Directly

The SDK is a thin wrapper around the REST API. If you prefer, you can call the API directly:

// If you prefer not to use the SDK, a single fetch call works:
const response = await fetch('https://api.xident.io/api/v1/verification-tokens/verify', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.XIDENT_SECRET_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ token })
});

const { success, data } = await response.json();
// data.verified, data.age_bracket, data.session_id, data.metadata

Related