npm install @keverdjs/node

import { Keverd } from '@keverdjs/node';

const keverd = new Keverd({
  secretKey: process.env.KEVERD_SECRET_KEY!, // kv_sk_live_… or kv_sk_test_…
  // baseUrl: 'https://api.keverd.com',
  // timeoutMs: 30000,
});

const result = await keverd.verify(eventId);

if (result.action === 'block') {
  // reject
} else if (result.action === 'soft_challenge' || result.action === 'hard_challenge') {
  // step-up auth
} else {
  // allow
}

POST https://api.keverd.com/v2/verify
X-Secret-API-Key: kv_sk_…
Content-Type: application/json

{
  "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

{
  "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "fingerprint": "kvd_…",
  "visitor_id": "kvd_…",
  "risk_score": 42,
  "recommendation": "allow",
  "action": "allow",
  "reason": ["VPN_DETECTED"],
  "reasons": [
    {
      "code": "VPN_DETECTED",
      "explanation": "The connection appears to route through a VPN.",
      "evidence": {}
    }
  ],
  "score": 0.42,
  "trust_score": 70,
  "reputation_score": null,
  "signals": {},
  "detection": {
    "vpn": { "detected": true, "confidence": 0.72, "method": "ip_mismatch" },
    "riskScore": 0.48,
    "riskLevel": "MEDIUM"
  },
  "smart_signals": {
    "vpn_detected": true,
    "incognito_detected": false,
    "tor_detected": false,
    "datacenter_detected": false,
    "action": "allow",
    "risk_score": 42
  },
  "created_at": "2026-07-25T12:00:00Z",
  "country_code": "KE",
  "country_name": "Kenya",
  "page_url": "https://example.com/login",
  "page_origin": "https://example.com",
  "location": {
    "ip": "203.0.113.10",
    "country_code": "KE",
    "country_name": "Kenya"
  },
  "ip_info": {
    "asn": "13335",
    "asn_name": "Example ISP",
    "datacenter": false
  },
  "times_seen": 3,
  "first_seen": "2026-07-01T09:00:00Z",
  "last_seen": "2026-07-25T12:00:00Z",
  "is_new": false,
  "device_history": {
    "times_seen": 3,
    "first_seen": "2026-07-01T09:00:00Z",
    "last_seen": "2026-07-25T12:00:00Z",
    "is_new": false,
    "unique_ip_count": 2,
    "unique_country_count": 1,
    "last_seen_events": [
      {
        "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "timestamp": "2026-07-25T12:00:00Z",
        "ip_address": "203.0.113.10",
        "country_code": "KE",
        "country_name": "Kenya",
        "page_url": "https://example.com/login",
        "page_origin": "https://example.com",
        "risk_score": 42,
        "action": "allow"
      }
    ]
  }
}

{
  "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "email": "user@example.com",
  "password": "…"
}

import express from 'express';
import { Keverd } from '@keverdjs/node';

const app = express();
const keverd = new Keverd({ secretKey: process.env.KEVERD_SECRET_KEY! });

app.post('/login', express.json(), async (req, res) => {
  const { eventId } = req.body;
  const risk = await keverd.verify(eventId);

  if (risk.action === 'block') {
    return res.status(403).json({ error: 'Blocked', reasons: risk.reasons });
  }

  res.json({ ok: true, visitorId: risk.visitor_id, timesSeen: risk.times_seen });
});

app.post(
  '/webhooks/keverd',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const event = keverd.webhooks.constructEvent(
      req.body, // raw Buffer — do not JSON.parse first
      req.headers['x-keverd-signature'] as string,
      process.env.KEVERD_WEBHOOK_SECRET!, // whsec_…
    );

    if (event.type === 'verification.completed') {
      const verification = event.data.object; // same JSON as verify()
    }

    res.sendStatus(200);
  },
);

try {
  await keverd.verify({ eventId });
} catch (err) {
  if (err instanceof KeverdAPIError && err.statusCode === 402) {
    // Workspace quota exceeded — upgrade plan or wait for reset
  }
  throw err;
}

import { Keverd, KeverdAPIError, KeverdError, KeverdSignatureError } from '@keverdjs/node';