# Android SDK Source: https://developer.keverd.com/android Device fingerprinting and login verify with com.keverd:fraud-sdk # Android SDK Same dashboard and API as the web SDKs. The Android SDK **collects** device signals with a **public** key and returns an `eventId`. Your backend **verifies** with a **secret** key. ## Requirements * Min SDK **21**, Target SDK **36** * Kotlin **1.9+** (Java 11 bytecode) * Internet access on device ## Install **Maven Central:** ```kotlin theme={null} dependencies { implementation("com.keverd:fraud-sdk:1.0.0") } ``` Private GitHub Packages publishing is also supported for internal builds — use the same `com.keverd:fraud-sdk` coordinates when configured. ## API keys Use a **public** key only (`kv_pk_test_…` / `kv_pk_live_…`). Never put a secret key (`kv_sk_…`) in the Android app. Secret keys are for [server verify](/server/overview) only. Get keys at [dashboard.keverd.com](https://dashboard.keverd.com) → **Integrate → API keys**. See [API keys](/api-keys). ## Permissions Merged from the library manifest: | Permission | Required | Purpose | | ---------------------- | -------- | ------------------------------------------------ | | `INTERNET` | Yes | API calls | | `ACCESS_NETWORK_STATE` | Yes | Network signals | | `READ_PHONE_STATE` | Optional | Richer SIM / mobile signals (request at runtime) | ## Initialize Call once — typically in `Application.onCreate`: ```kotlin theme={null} import com.keverd.sdk.Config import com.keverd.sdk.Keverd class App : Application() { override fun onCreate() { super.onCreate() Keverd.init( this, Config( apiKey = BuildConfig.KEVERD_PUBLIC_KEY, // kv_pk_… endpoint = "https://api.keverd.com", // optional consentRequired = true, // default true debug = BuildConfig.DEBUG, // optional ), ) } } ``` ### `Config` | Field | Required | Default | Notes | | ----------------- | -------- | ------------------------ | --------------------------------------------------- | | `apiKey` | **Yes** | — | Public key (`kv_pk_…`) | | `endpoint` | No | `https://api.keverd.com` | API base URL | | `userId` | No | `null` | Optional integrator id | | `consentRequired` | No | `true` | When `true`, call `setConsent(true)` before collect | | `debug` | No | `false` | Logs OkHttp request/response | ## Consent When `consentRequired = true` (default): ```kotlin theme={null} Keverd.setConsent(true) ``` Without consent, `getVisitorData()` fails with `KeverdError.Code.CONSENT_REQUIRED` (or returns `Result.ConsentRequired` on the callback API). ## Collect ### Kotlin (suspend) ```kotlin theme={null} lifecycleScope.launch { try { val data = Keverd.getVisitorData() // Send data.eventId to your backend Log.d("Keverd", "visitor=${data.visitorId} risk=${data.riskScore} action=${data.action}") } catch (e: KeverdError) { Log.e("Keverd", "${e.code}: ${e.message}") } } ``` ### Callback (Java-friendly) ```kotlin theme={null} Keverd.getVisitorData { result -> when (result) { is Result.Success -> { val data = result.data // data.eventId → your backend } is Result.ConsentRequired -> { /* show consent UI */ } is Result.Error -> { Log.e("Keverd", "${result.error.code}: ${result.error.message}") } } } ``` `getVisitorData()` calls **`POST /v2/fingerprint`** with header `X-API-Key` (and `X-SDK-Source: android`). ## Response (`VisitorData`) | Field | Type | Notes | | ------------------------------------------------ | -------------- | ---------------------------------------------------- | | `visitorId` | `String` | Stable device id (`kvd_…`, from API `fingerprint`) | | `eventId` | `String` | **Send this to your server** for verify | | `requestId` | `String` | Same id family as `eventId` | | `sessionId` | `String` | Session id | | `riskScore` | `Int` | 0–100 style score from collect | | `score` | `Double` | Normalized score | | `action` | `Action` | `ALLOW`, `SOFT_CHALLENGE`, `HARD_CHALLENGE`, `BLOCK` | | `reasons` | `List` | Reason codes | | `similarity` | `Double?` | Optional | | `isNew` / `timesSeen` / `firstSeen` / `lastSeen` | optional | Device history hints | | `adaptiveResponse` | optional | Challenge hints when present | Send the event id to your backend: ```json theme={null} { "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` Your server then calls [POST /v2/verify](/api-reference/verify) with `{ "event_id": "…" }` using a **secret** key. See [Server SDKs](/server/overview). There is no separate `getVisitorId()` API. Use `VisitorData.visitorId` after `getVisitorData()`. ## Login verification (collect with login context) Attaches login context to the collect request (`POST /fingerprint/verify/login`). This still uses the **public** key and does **not** replace server `verify()`. ```kotlin theme={null} import com.keverd.sdk.util.LoginIdentifierHash import com.keverd.sdk.verify.AuthMethod import com.keverd.sdk.verify.LoginContext import com.keverd.sdk.verify.LoginResult import com.keverd.sdk.verify.VerifyLoginOptions val data = Keverd.verifyLogin( VerifyLoginOptions( login = LoginContext( identifierHash = LoginIdentifierHash.fromIdentifier(email), result = LoginResult.SUCCESS, // or FAILURE authMethod = AuthMethod.PASSWORD, mfaUsed = true, ), ), ) // Still send data.eventId to your backend for authoritative verify ``` `LoginIdentifierHash.fromIdentifier(identifier)` produces `sha256:` of the lowercased identifier (optional salt). Never send raw emails/phones as the hash input if your policy forbids it — hash client-side first. ### `LoginContext` | Field | Type | Notes | | ---------------- | ------------- | ------------------------------------------------ | | `identifierHash` | `String` | Prefer `LoginIdentifierHash.fromIdentifier(...)` | | `result` | `LoginResult` | `SUCCESS` \| `FAILURE` | | `failureReason` | `String?` | Optional | | `authMethod` | `AuthMethod` | e.g. `PASSWORD`, `SSO`, `PASSKEY`, `UNKNOWN` | | `mfaUsed` | `Boolean?` | Optional | | `attemptId` | `String?` | Optional | ## Behavioral signals (optional) Improve signal quality by attaching listeners on screens where users interact: ```kotlin theme={null} // Activity — touch kinematics Keverd.attachBehavioralMonitoring(this) // Login / form fields — keystroke timing Keverd.attachToEditText(binding.emailEditText) Keverd.attachToEditText(binding.passwordEditText) // Or a custom touch listener view.setOnTouchListener(Keverd.createTouchListener()) ``` ## Preview signals (debug) ```kotlin theme={null} val snapshot = Keverd.previewCollectedSignals() // Local signals only — does not call the API ``` Useful in the sample app / debug builds. Do not use as a substitute for `getVisitorData()`. ## Errors Suspend APIs throw `KeverdError`. The callback API returns `Result.Error(KeverdError)`. | `KeverdError.Code` | When | | ------------------ | ----------------------------------- | | `NOT_INITIALIZED` | `Keverd.init` not called | | `CONSENT_REQUIRED` | Consent gate blocked collect | | `UNAUTHORIZED` | HTTP 401 (bad / missing public key) | | `INVALID_REQUEST` | HTTP 400 | | `NETWORK_ERROR` | Timeout / connectivity | | `SERVER_ERROR` | HTTP 5xx | | `PARSE_ERROR` | Unexpected / incomplete API payload | | `UNKNOWN` | Other failures | ```kotlin theme={null} try { Keverd.getVisitorData() } catch (e: KeverdError) { when (e.code) { KeverdError.Code.CONSENT_REQUIRED -> { /* prompt user */ } KeverdError.Code.UNAUTHORIZED -> { /* check kv_pk_ key */ } KeverdError.Code.NETWORK_ERROR -> { /* retry */ } else -> Log.e("Keverd", e.message, e) } } ``` ## ProGuard / R8 The published AAR ships consumer ProGuard rules that keep the public SDK surface (`Keverd`, `Config`, `VisitorData`, `Result*`, `KeverdError`, `Action`, verify types, and API DTOs). Extra keep rules are usually unnecessary. ## Deprecated API `KeverdFingerprint.init` / `submit(...)` remains as a thin 1.0.x migration wrapper. Prefer: ```kotlin theme={null} Keverd.init(context, config) Keverd.setConsent(true) Keverd.getVisitorData() ``` ## End-to-end flow 1. App calls `Keverd.getVisitorData()` with `kv_pk_…` 2. App sends `eventId` to your backend 3. Backend calls [POST /v2/verify](/api-reference/verify) with `kv_sk_…` and `{ "event_id": "…" }` 4. Enforce returned `action`: `allow` | `soft_challenge` | `hard_challenge` | `block` Optional: subscribe to [webhooks](/server/webhooks) after verify. ## Next * [Server SDKs](/server/overview) * [Node.js verify](/node-js) * [POST /v2/verify](/api-reference/verify) * [API keys](/api-keys) # API keys Source: https://developer.keverd.com/api-keys Public, secret, and webhook secrets # API keys Create and manage keys in the dashboard: **Integrate → API keys**. | Type | Prefix | Use | | ------- | ----------------------------- | ---------------------------- | | Public | `kv_pk_test_` / `kv_pk_live_` | Browser & mobile SDKs | | Secret | `kv_sk_test_` / `kv_sk_live_` | Server `verify`, secret APIs | | Webhook | `whsec_` | Verify inbound webhooks | * Use **test** keys in development, **live** in production. * Public keys are safe in frontend env vars (`NEXT_PUBLIC_…`, `VITE_…`) and in the CDN URL path (`https://cdn.keverd.com/v1/kv_pk_…/keverd.min.js`). Copy them anytime from the dashboard. * Secret keys belong in server env / secrets manager only. To view a secret again, request a **verification code** by email, enter it in the dashboard, then copy — the key itself is never emailed. * Key **names** must be unique within a workspace. * On create, the full key is shown once in the dashboard. Store it immediately. # POST /v2/verify Source: https://developer.keverd.com/api-reference/verify Billable server-side decision for an event_id # POST /v2/verify Billable verify. Use a **secret** API key (`kv_sk_…`). Never call this from the browser. ## Request `Content-Type: application/json` ```http theme={null} POST https://api.keverd.com/v2/verify X-Secret-API-Key: kv_sk_live_… Content-Type: application/json ``` ```json theme={null} { "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` | Field | Type | Required | Description | | ---------- | ------------- | -------- | --------------------------------------------------------------------------- | | `event_id` | string (UUID) | Yes | Event id from browser/mobile collect (`getVisitorData` / React `requestId`) | ## Response `Content-Type: application/json` ```json theme={null} { "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "fingerprint": "kvd_…", "visitor_id": "kvd_…", "risk_score": 42, "recommendation": "allow", "action": "allow", "reason": ["VPN_DETECTED", "INCOGNITO_DETECTED"], "reasons": [ { "code": "VPN_DETECTED", "explanation": "The connection appears to route through a VPN.", "evidence": { "ip": "203.0.113.10", "asn": "13335", "asn_name": "Example ISP", "webrtc": { "request_ip": "203.0.113.10", "webrtc_public_ips": ["198.51.100.20"], "webrtc_matches_request": false } } } ], "score": 0.42, "trust_score": 70, "reputation_score": null, "signals": { "hardware": {}, "software": {}, "network": {}, "session": {} }, "smart_signals": { "vpn_detected": true, "proxy_detected": false, "tor_detected": false, "incognito_detected": true, "datacenter_detected": false, "bot_detected": false, "risk_score": 42, "action": "allow", "browser": "Chrome", "operating_system": "macOS", "location": { "ip": "203.0.113.10", "city": "Nairobi", "country_code": "KE", "country_name": "Kenya", "ip_timezone": "Africa/Nairobi" }, "ip_info": { "asn": "13335", "asn_name": "Example ISP", "asn_network": "203.0.113.0/24", "asn_type": "isp", "datacenter": false, "org": "Example ISP" } }, "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", "city": "Nairobi", "country_code": "KE", "country_name": "Kenya", "region": "Nairobi City", "ip_timezone": "Africa/Nairobi", "latitude": -1.286389, "longitude": 36.817223 }, "ip_info": { "asn": "13335", "asn_name": "Example ISP", "asn_network": "203.0.113.0/24", "asn_type": "isp", "datacenter": false, "org": "Example ISP" }, "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" } ] } } ``` ### Response fields | Field | Type | Description | | ------------------------------- | -------------- | ---------------------------------------------------------- | | `event_id` | string | Verified event id | | `fingerprint` / `visitor_id` | string \| null | Workspace-scoped visitor id | | `risk_score` | number \| null | 0–100 | | `action` / `recommendation` | string \| null | `allow` \| `soft_challenge` \| `hard_challenge` \| `block` | | `reason` | string\[] | Flat reason codes (back-compat) | | `reasons` | object\[] | `{ code, explanation, evidence? }` | | `score` | number \| null | Normalized score (0–1 when present) | | `trust_score` | number \| null | Device trust rollup when available | | `reputation_score` | number \| null | Network reputation when available | | `signals` | object \| null | Raw client signals for this event | | `smart_signals` | object \| null | Derived flags + scores | | `location` | object \| null | Geo from IP enrichment | | `ip_info` | object \| null | ASN / ISP / datacenter | | `times_seen` | number | Sight visits in this workspace | | `first_seen` / `last_seen` | string \| null | ISO-8601 timestamps | | `is_new` | boolean | `true` when `times_seen <= 1` | | `device_history` | object | Full history bag (includes last 5 events) | | `page_url` / `page_origin` | string \| null | Page context from collect | | `country_code` / `country_name` | string \| null | From event geo | | `created_at` | string \| null | Event timestamp (ISO-8601) | `device_history.last_seen_events` is newest-first (up to 5), including the verified event when present. ## Errors | Status | Body / meaning | | ------ | --------------------------------- | | 400 | Missing / invalid `event_id` | | 401 | Bad secret key | | 402 | Protected-device quota exceeded | | 404 | Event not found / wrong workspace | Prefer the [Node](/node-js), [Python](/server/python), or [PHP](/server/php) SDKs over raw HTTP. # Welcome to Keverd Docs Source: https://developer.keverd.com/index Identify devices, score risk, and stop fraud. # Welcome to Keverd Docs Keverd helps you identify devices and decide risk on login, checkout, and other sensitive actions. ## How it works 1. **Collect in the browser or Android app** with a **public** API key (`kv_pk_…`) → JSON / `eventId` 2. Send that id to your backend as JSON, e.g. `{ "eventId": "…" }` 3. **Verify on the server** with a **secret** API key (`kv_sk_…`) → `{ "event_id": "…" }` request, decision JSON response 4. Enforce the returned **`action`**: `allow`, `soft_challenge`, `hard_challenge`, or `block` Full verify payload (including `device_history`, `location`, `ip_info`): [POST /v2/verify](/api-reference/verify). ## Start here * [Quickstart](/quickstart) * [JavaScript SDK](/java-script-1) (npm or [CDN](https://cdn.keverd.com)) * [Android SDK](/android) * [Node.js server SDK](/node-js) * [Webhooks](/server/webhooks) ## Keys | Key | Prefix | Where | | ------- | ----------------------------- | ------------------------------ | | Public | `kv_pk_test_` / `kv_pk_live_` | Browser / mobile SDKs | | Secret | `kv_sk_test_` / `kv_sk_live_` | Your servers only | | Webhook | `whsec_` | Webhook signature verification | Get keys at [dashboard.keverd.com](https://dashboard.keverd.com) → **Integrate → API keys**. # JavaScript SDK Source: https://developer.keverd.com/java-script-1 Vanilla JS and CDN with @keverdjs/agent # JavaScript SDK Collect device signals in the browser with a **public** API key (`kv_pk_…`). Send the billable `event_id` / `requestId` to your backend and [verify on the server](/server/overview). ## Install ### npm ```bash theme={null} npm install @keverdjs/agent ``` ### CDN (no npm) Load the ESM bundle from [cdn.keverd.com](https://cdn.keverd.com). Put your **public** key in the URL path — `start()` reads it automatically. ```js theme={null} const keverdPromise = import( 'https://cdn.keverd.com/v1/YOUR_PUBLIC_API_KEY/keverd.min.js' ).then((Keverd) => Keverd.start()); keverdPromise .then((k) => k.getVisitorData()) .then((r) => { console.log(r.event_id || r.requestId); // billable event id — send to your server console.log(r.visitor_id || r.visitorId); // persistent device id }); ``` Replace `YOUR_PUBLIC_API_KEY` with `kv_pk_test_…` or `kv_pk_live_…`. ```html theme={null} ``` CDN and browser SDKs use **public** keys only. Never put `kv_sk_…` or `whsec_…` in frontend code. `start()` can also take an explicit key: `start('kv_pk_…')` or `start({ apiKey: 'kv_pk_…', endpoint: 'https://api.keverd.com' })` if you are not loading from the keyed CDN path. ## Initialize (npm) ```js theme={null} import { Keverd } from '@keverdjs/agent'; Keverd.init('kv_pk_live_…'); // or Keverd.init({ apiKey: 'kv_pk_test_…', endpoint: 'https://api.keverd.com', }); ``` ## Collect ```js theme={null} const result = await Keverd.getVisitorData(); console.log(result.visitor_id); // persistent device id console.log(result.event_id); // send to your server console.log(result.risk_score); // UI hint only console.log(result.browser); // e.g. "Chrome" ``` SDK aliases (same values): `visitorId` ↔ `visitor_id`, `requestId` ↔ `event_id`. ### Response JSON ```json theme={null} { "visitor_id": "kvd_…", "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "risk_score": 12, "browser": "Chrome", "visitorId": "kvd_…", "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "session_id": "kvd_…" } ``` Canonical fields are `visitor_id`, `event_id`, `risk_score`, `browser`. Extra keys are **aliases** (same values) so older installed SDKs keep working. Collect does **not** return authoritative `action` / `reasons` — use [POST /v2/verify](/api-reference/verify). Send this to your backend (JSON body example): ```json theme={null} { "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` Your server then calls [POST /v2/verify](/api-reference/verify) with `{ "event_id": "…" }`. Do not use `Keverd.get()` for the verify flow. It returns a **string**, not an object with `event_id`. ## Optional use-case helpers (public key — still collection) ```js theme={null} await Keverd.verifyLogin({ /* … */ }); await Keverd.verifyCheckout(amount, currency); await Keverd.verifyRegistration(); await Keverd.verifyPasswordReset(); await Keverd.verifyAccountChange(); ``` These return the same collect JSON shape. They do **not** replace server `verify()`. ## Next * [Quickstart](/quickstart) * [Verify on the server →](/server/overview) * [API keys](/api-keys) # Next.js Source: https://developer.keverd.com/nextjs-quickstart App Router with @keverdjs/react and server verify # Next.js ## Env ```bash theme={null} NEXT_PUBLIC_KEVERD_PUBLIC_KEY=kv_pk_test_… KEVERD_SECRET_KEY=kv_sk_test_… ``` ```bash theme={null} npm install @keverdjs/react @keverdjs/node ``` ## Provider (App Router) ```tsx theme={null} // app/components/KeverdWrapper.tsx 'use client'; import { KeverdProvider } from '@keverdjs/react'; export function KeverdWrapper({ children }: { children: React.ReactNode }) { return ( {children} ); } ``` Wrap children with `KeverdWrapper` in `app/layout.tsx`. ## Client collect ```tsx theme={null} 'use client'; import { useKeverdVisitorData } from '@keverdjs/react'; export default function LoginPage() { const { getData, isLoading } = useKeverdVisitorData({ immediate: false }); async function login() { const visitor = await getData(); await fetch('/api/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ eventId: visitor.requestId }), }); } return ( ); } ``` ### Client → `/api/login` request JSON ```json theme={null} { "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` `visitor.requestId` is the collect `event_id`. ## Server verify ```ts theme={null} // app/api/login/route.ts import { Keverd } from '@keverdjs/node'; import { NextResponse } from 'next/server'; const keverd = new Keverd({ secretKey: process.env.KEVERD_SECRET_KEY! }); export async function POST(req: Request) { const { eventId } = await req.json(); const decision = await keverd.verify(eventId); if (decision.action === 'block') { return NextResponse.json( { error: 'Blocked', reasons: decision.reasons }, { status: 403 }, ); } return NextResponse.json({ ok: true, visitorId: decision.visitor_id, timesSeen: decision.times_seen, isNew: decision.is_new, }); } ``` ### Keverd `verify` request JSON (SDK → API) ```json theme={null} { "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` ### Example success response from your route ```json theme={null} { "ok": true, "visitorId": "kvd_…", "timesSeen": 3, "isNew": false } ``` ### Example block response from your route ```json theme={null} { "error": "Blocked", "reasons": [ { "code": "VPN_DETECTED", "explanation": "The connection appears to route through a VPN.", "evidence": {} } ] } ``` Full Keverd decision object: [POST /v2/verify](/api-reference/verify). # Node.js SDK Source: https://developer.keverd.com/node-js @keverdjs/node — verify and webhooks # Node.js SDK ```bash theme={null} npm install @keverdjs/node ``` Requires Node 18+. Zero runtime dependencies. ## Initialize + verify ```ts theme={null} 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 } ``` Maps to: ```http theme={null} POST https://api.keverd.com/v2/verify X-Secret-API-Key: kv_sk_… Content-Type: application/json ``` ```json theme={null} { "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` ## Verify response (JSON) `keverd.verify()` resolves to this object (same as [POST /v2/verify](/api-reference/verify)): ```json theme={null} { "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" } ] } } ``` `action` / `recommendation`: `allow` | `soft_challenge` | `hard_challenge` | `block` ## Express Your route typically accepts JSON from the browser: ```json theme={null} { "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "email": "user@example.com", "password": "…" } ``` ```ts theme={null} 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 }); }); ``` ## Webhooks ```ts theme={null} 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); }, ); ``` See [Webhooks](/server/webhooks) for the full envelope JSON. ## Errors All SDK failures extend `KeverdError`. Catch the specific subclass when you need different handling. ### `KeverdError` Base error for client-side failures before a successful API response, or when the request never completes. **Thrown when** * Missing config (e.g. no `secretKey`) * Invalid arguments (e.g. empty `eventId`) * Network failures * Request timeouts **Fields:** `message`, `code` (string | null), `statusCode` (number | null) ### `KeverdAPIError` Thrown when the API returns a **non-2xx** HTTP status. Extends `KeverdError`. **Thrown when** * Auth fails (`401` / `403`) * Bad request (`400`) * Quota exceeded (`402`) * Server errors (`5xx`) **Fields:** `statusCode`, `code`, `body` (parsed JSON when available) ```ts theme={null} 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; } ``` ### `KeverdSignatureError` Thrown by `keverd.webhooks.constructEvent(...)` when webhook signature verification fails. Extends `KeverdError` with `code: "invalid_signature"`. **Thrown when** * Missing `X-Keverd-Signature` or webhook secret * Malformed signature header * Timestamp outside the 300s tolerance * HMAC mismatch (wrong secret, or body was parsed/modified before verify) * Payload is not valid JSON Treat these as **untrusted requests** — return `400` and do not process the event. See [Webhooks](/server/webhooks). ```ts theme={null} import { Keverd, KeverdAPIError, KeverdError, KeverdSignatureError } from '@keverdjs/node'; ``` | Class | Typical cause | | ---------------------- | ------------------------------------------------------- | | `KeverdError` | Validation, network, timeout | | `KeverdAPIError` | Non-2xx from API (`statusCode`, `body`) — `402` = quota | | `KeverdSignatureError` | Bad or missing webhook signature | # PHP SDK Source: https://developer.keverd.com/php-laravel keverd/keverd — verify and webhooks # PHP SDK ```bash theme={null} composer require keverd/keverd ``` PHP 8.1+ with `curl` and `json`. ## Initialize + verify ```php theme={null} getenv('KEVERD_SECRET_KEY'), // kv_sk_… ]); $result = $keverd->verify($eventId); if (($result['action'] ?? null) === 'block') { // reject } elseif (($result['action'] ?? null) === 'allow') { // continue } ``` HTTP under the hood: ```http theme={null} POST https://api.keverd.com/v2/verify X-Secret-API-Key: kv_sk_… Content-Type: application/json ``` ```json theme={null} { "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` ## Verify response (JSON) `$keverd->verify()` returns an associative array matching [POST /v2/verify](/api-reference/verify): ```json theme={null} { "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": {}, "smart_signals": { "vpn_detected": true, "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" }, "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": [] } } ``` ## Laravel Browser → your route (JSON): ```json theme={null} { "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "email": "user@example.com", "password": "…" } ``` ```php theme={null} use Keverd\Keverd; use Illuminate\Http\Request; Route::post('/login', function (Request $request) { $keverd = new Keverd(['secretKey' => config('services.keverd.secret')]); $risk = $keverd->verify($request->input('eventId')); if (($risk['action'] ?? null) === 'block') { return response()->json([ 'error' => 'Blocked', 'reasons' => $risk['reasons'] ?? [], ], 403); } return response()->json([ 'ok' => true, 'visitorId' => $risk['visitor_id'] ?? null, 'timesSeen' => $risk['times_seen'] ?? null, 'isNew' => $risk['is_new'] ?? null, ]); }); ``` ## Webhooks Inbound JSON matches the [webhook envelope](/server/webhooks). Verify signature on the **raw** body. ```php theme={null} Route::post('/webhooks/keverd', function (Request $request) { $keverd = new Keverd(['secretKey' => config('services.keverd.secret')]); $event = $keverd->webhooks->constructEvent( $request->getContent(), // raw body $request->header('X-Keverd-Signature', ''), config('services.keverd.webhook_secret'), ); if ($event['type'] === 'verification.completed') { $verification = $event['data']['object']; // same JSON as verify() } return response()->noContent(); }); ``` You can also call `Keverd\Webhooks::constructEvent(...)`. ## Errors All SDK failures extend `Keverd\KeverdError`. Catch the specific subclass when you need different handling. ### `Keverd\KeverdError` Base exception for client-side failures before a successful API response, or when the request never completes. **Thrown when** * Missing config (e.g. no `secretKey`) * Invalid arguments (e.g. empty `eventId`) * Network failures * Request timeouts ### `Keverd\KeverdApiError` Thrown when the API returns a **non-2xx** HTTP status. Extends `KeverdError`. **Thrown when** * Auth fails (`401` / `403`) * Bad request (`400`) * Quota exceeded (`402`) * Server errors (`5xx`) Inspect the status code and response body on the exception to decide whether to retry or surface an error. ### `Keverd\KeverdSignatureError` Thrown by `$keverd->webhooks->constructEvent(...)` when webhook signature verification fails. Extends `KeverdError`. **Thrown when** * Missing `X-Keverd-Signature` or webhook secret * Malformed signature header * Timestamp outside the 300s tolerance * HMAC mismatch (wrong secret, or body was parsed/modified before verify) * Payload is not valid JSON Treat these as **untrusted requests** — return `400` and do not process the event. See [Webhooks](/server/webhooks). | Class | Typical cause | | ----------------------------- | -------------------------------- | | `Keverd\KeverdError` | Validation, network, timeout | | `Keverd\KeverdApiError` | Non-2xx from API — `402` = quota | | `Keverd\KeverdSignatureError` | Bad or missing webhook signature | # Python SDK Source: https://developer.keverd.com/python keverd — verify and webhooks # Python SDK ```bash theme={null} pip install keverd ``` Python 3.9+. Zero runtime dependencies. ## Initialize + verify ```python theme={null} import os from keverd import Keverd keverd = Keverd(secret_key=os.environ["KEVERD_SECRET_KEY"]) # kv_sk_… result = keverd.verify(event_id) if result.get("action") == "block": ... elif result.get("action") == "allow": ... ``` HTTP under the hood: ```http theme={null} POST https://api.keverd.com/v2/verify X-Secret-API-Key: kv_sk_… Content-Type: application/json ``` ```json theme={null} { "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` ## Verify response (JSON) `keverd.verify()` returns a dict matching [POST /v2/verify](/api-reference/verify): ```json theme={null} { "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, "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" }, "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": [] } } ``` ## FastAPI Client → your API (JSON body): ```json theme={null} { "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "email": "user@example.com", "password": "…" } ``` ```python theme={null} import os from fastapi import FastAPI, HTTPException from pydantic import BaseModel from keverd import Keverd app = FastAPI() keverd = Keverd(secret_key=os.environ["KEVERD_SECRET_KEY"]) class LoginBody(BaseModel): event_id: str email: str password: str @app.post("/login") def login(body: LoginBody): risk = keverd.verify(body.event_id) if risk.get("action") == "block": raise HTTPException( status_code=403, detail={"error": "Blocked", "reasons": risk.get("reasons")}, ) return { "ok": True, "visitor_id": risk.get("visitor_id"), "times_seen": risk.get("times_seen"), "is_new": risk.get("is_new"), } ``` ## Webhooks Inbound body is the [webhook envelope](/server/webhooks) (JSON). Verify signature on **raw bytes** first. ```python theme={null} import os from fastapi import Request, Response @app.post("/webhooks/keverd") async def keverd_webhook(request: Request): raw = await request.body() # raw bytes — do not parse first event = keverd.webhooks.construct_event( raw, request.headers.get("x-keverd-signature", ""), os.environ["KEVERD_WEBHOOK_SECRET"], ) if event["type"] == "verification.completed": verification = event["data"]["object"] # same JSON as verify() return Response(status_code=200) ``` ## Errors All SDK failures subclass `KeverdError`. Catch the specific type when you need different handling. ### `KeverdError` Base exception for client-side failures before a successful API response, or when the request never completes. **Raised when** * Missing config (e.g. no `secret_key`) * Invalid arguments (e.g. empty `event_id`) * Network failures * Request timeouts **Attributes:** `args` / message, `code` (`str | None`), `status_code` (`int | None`) ### `KeverdAPIError` Raised when the API returns a **non-2xx** HTTP status. Subclasses `KeverdError`. **Raised when** * Auth fails (`401` / `403`) * Bad request (`400`) * Quota exceeded (`402`) * Server errors (`5xx`) **Attributes:** `status_code`, `code`, `body` (parsed JSON when available) ```python theme={null} from keverd import KeverdAPIError try: keverd.verify(event_id=event_id) except KeverdAPIError as err: if err.status_code == 402: # Workspace quota exceeded — upgrade plan or wait for reset raise raise ``` ### `KeverdSignatureError` Raised by `keverd.webhooks.construct_event(...)` when webhook signature verification fails. Subclasses `KeverdError` with `code="invalid_signature"`. **Raised when** * Missing `X-Keverd-Signature` or webhook secret * Malformed signature header * Timestamp outside the 300s tolerance * HMAC mismatch (wrong secret, or body was parsed/modified before verify) * Payload is not valid JSON Treat these as **untrusted requests** — return `400` and do not process the event. See [Webhooks](/server/webhooks). ```python theme={null} from keverd import Keverd, KeverdAPIError, KeverdError, KeverdSignatureError ``` | Class | Typical cause | | ---------------------- | -------------------------------------------------------- | | `KeverdError` | Validation, network, timeout | | `KeverdAPIError` | Non-2xx from API (`status_code`, `body`) — `402` = quota | | `KeverdSignatureError` | Bad or missing webhook signature | # JavaScript SDK Source: https://developer.keverd.com/quickstart Vanilla JS and CDN with @keverdjs/agent # JavaScript SDK Collect device signals in the browser with a **public** API key (`kv_pk_…`). Send the billable `event_id` / `requestId` to your backend and [verify on the server](/server/overview). ## Install ### npm ```bash theme={null} npm install @keverdjs/agent ``` ### CDN (no npm) Load the ESM bundle from [cdn.keverd.com](https://cdn.keverd.com). Put your **public** key in the URL path — `start()` reads it automatically. ```js theme={null} const keverdPromise = import( 'https://cdn.keverd.com/v1/YOUR_PUBLIC_API_KEY/keverd.min.js' ).then((Keverd) => Keverd.start()); keverdPromise .then((k) => k.getVisitorData()) .then((r) => { console.log(r.requestId); // billable event id — send to your server console.log(r.visitorId); // persistent device id }); ``` Replace `YOUR_PUBLIC_API_KEY` with `kv_pk_test_…` or `kv_pk_live_…`. ```html theme={null} ``` CDN and browser SDKs use **public** keys only. Never put `kv_sk_…` or `whsec_…` in frontend code. `start()` can also take an explicit key: `start('kv_pk_…')` or `start({ apiKey: 'kv_pk_…', endpoint: 'https://api.keverd.com' })` if you are not loading from the keyed CDN path. ## Initialize (npm) ```js theme={null} import { Keverd } from '@keverdjs/agent'; Keverd.init('kv_pk_live_…'); // or Keverd.init({ apiKey: 'kv_pk_test_…', endpoint: 'https://api.keverd.com', }); ``` ## Collect ```js theme={null} const result = await Keverd.getVisitorData(); console.log(result.event_id); // send to your server console.log(result.requestId); // same billable id (CDN-friendly alias) console.log(result.fingerprint); // persistent device id console.log(result.visitorId); // alias of fingerprint console.log(result.action); // allow | soft_challenge | hard_challenge | block console.log(result.risk_score); ``` ### Response JSON ```json theme={null} { "fingerprint": "kvd_…", "visitorId": "kvd_…", "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "session_id": "…", "risk_score": 12, "score": 0.12, "action": "allow", "reason": [], "similarity": 0.98, "is_new": false, "times_seen": 3, "first_seen": "2026-07-01T09:00:00.000000", "last_seen": "2026-07-25T12:00:00.000000" } ``` Send this to your backend (JSON body example): ```json theme={null} { "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` Your server then calls [POST /v2/verify](/api-reference/verify) with `{ "event_id": "…" }`. Do not use `Keverd.get()` for the verify flow. It returns a **string**, not an object with `event_id`. ## Optional use-case helpers (public key — still collection) ```js theme={null} await Keverd.verifyLogin({ /* … */ }); await Keverd.verifyCheckout(amount, currency); await Keverd.verifyRegistration(); await Keverd.verifyPasswordReset(); await Keverd.verifyAccountChange(); ``` These return the same collect JSON shape. They do **not** replace server `verify()`. ## Next * [Quickstart](/quickstart) * [Verify on the server →](/server/overview) * [API keys](/api-keys) # React SDK Source: https://developer.keverd.com/react KeverdProvider and hooks for React # React SDK ## Install ```bash theme={null} npm install @keverdjs/react ``` ## Provider ```tsx theme={null} import { KeverdProvider } from '@keverdjs/react'; export function App() { return ( ); } ``` Use `kv_pk_…` only. Provider prepares the SDK; collection starts when a hook runs. ## `useKeverd()` (UI convenience) ```tsx theme={null} import { useKeverd } from '@keverdjs/react'; function Checkout() { const { deviceId, riskScore, isLoading, error } = useKeverd(); if (isLoading) return

Identifying device…

; if (error) return

{error.message}

; return (

Device: {deviceId}

Risk: {riskScore}

); } ``` ## `useKeverdVisitorData()` (send event to backend) ```tsx theme={null} import { useKeverdVisitorData } from '@keverdjs/react'; export function LoginForm() { const { getData, isLoading } = useKeverdVisitorData({ immediate: false }); async function onSubmit(form: { email: string; password: string }) { const visitor = await getData(); await fetch('/api/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email: form.email, password: form.password, eventId: visitor.requestId, }), }); } } ``` ### `getData()` result (JSON-shaped object) ```json theme={null} { "visitor_id": "kvd_…", "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "risk_score": 12, "browser": "Chrome" } ``` Aliases on the same object (and on the raw API for older SDKs): `visitorId`, `requestId`, `session_id`. | Field | Use | | ------------------------ | -------------------------------------- | | `event_id` / `requestId` | Send to your backend as the event id | | `risk_score` | UI hint only — **not** for enforcement | Action, reasons, and smart signals come from [POST /v2/verify](/api-reference/verify) — not from collect. Already-installed SDK versions that read `fingerprint` / `requestId` still work via API aliases. ### Request JSON your backend should expect ```json theme={null} { "email": "user@example.com", "password": "…", "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` Server then verifies with `{ "event_id": "" }` — see [POST /v2/verify](/api-reference/verify). Client `riskScore` is not enough for enforcement. Backend must call **`verify(eventId)`** and branch on **`action`**. ## Next [Server verify (Node) →](/node) # Overview Source: https://developer.keverd.com/server/overview Verify `event_id` on your backend # Server SDKs Browser SDKs **collect**. Server SDKs **verify**. | Step | Who | Key | Typical JSON | | ------- | ----------------- | --------- | --------------------------------------------- | | Collect | Browser / Android | `kv_pk_…` | Response includes `event_id` | | Verify | Your backend | `kv_sk_…` | Request `{ "event_id": "…" }` → decision JSON | `verify` is **billable**. Never call it from the browser. | Runtime | Package | Install | | ----------- | ---------------- | -------------------------------- | | Node 18+ | `@keverdjs/node` | `npm install @keverdjs/node` | | Python 3.9+ | `keverd` | `pip install keverd` | | PHP 8.1+ | `keverd/keverd` | `composer require keverd/keverd` | ## Flow **1. Browser collects** (public key) and gets JSON including `event_id` (React maps this to `requestId`). **2. Browser sends that id to your API**, for example: ```json theme={null} { "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "email": "user@example.com" } ``` **3. Your server verifies** (secret key): ```json theme={null} { "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` **4. Enforce** the returned `action` (`allow` | `soft_challenge` | `hard_challenge` | `block`). The full response also includes `reasons`, `smart_signals`, `location`, `ip_info`, and `device_history` — see [POST /v2/verify](/api-reference/verify). Webhooks are optional fan-out after verify ([envelope JSON](/server/webhooks)). * [Node.js](/node-js) * [Python](/python) * [PHP](/php-laravel) * [Webhooks](/server/webhooks) # Vue SDK Source: https://developer.keverd.com/vue Vue 3 plugin and composables # Vue SDK ```bash theme={null} npm install @keverdjs/vue ``` ```js theme={null} import { createApp } from 'vue'; import { KeverdPlugin } from '@keverdjs/vue'; import App from './App.vue'; createApp(App) .use(KeverdPlugin, { apiKey: import.meta.env.VITE_KEVERD_PUBLIC_KEY }) .mount('#app'); ``` ```vue theme={null} ``` ### Collect result (JSON-shaped) ```json theme={null} { "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "fingerprint": "kvd_…", "action": "allow", "risk_score": 12 } ``` ### Request JSON to your backend ```json theme={null} { "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` Server verifies with `{ "event_id": "…" }` — full response in [POST /v2/verify](/api-reference/verify). ## Next [Verify on the server →](/server/overview)