# 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)