API reference

The call you will make most. Send what you know about one user action; get back a verdict you can branch on and the evidence behind it. Event names are yours to choose (signup, trial_start, cashout, credit_redeem, …). Device-reuse and velocity signals sharpen with every event you send, so the same call gets better the longer you use it.

Request body

Response

Device profile (device)

Returned when the event carries a device_id. Server-side only, it goes to your backend, never the browser. Populated from the @kaidn/fp beacon and cheap history queries.

Two different fields identify a device here. id is the raw browser fingerprint: useful for debugging, but it collides across unrelated people, so it is not an identity. resolved_id is the identity, and resolution plus collision_risk tell you how much to trust it. Store a device_token as a first-party cookie (see @kaidn/sdk) and the resolution becomes deterministic. Device identity explains the three rungs, what each one links, and the measured risk behind each.

{
  "event_id": "719d4bb6-5083-41d9-852e-9331f8f703e4",
  "score": 95,
  "verdict": "block",
  "reasons": ["datacenter_ip", "device_reuse", "disposable_email"],
  "reason_text": "Strong indicators of abuse: the IP is a hosting provider
    address (amazon), this device is already linked to 3 accounts, and the
    email uses a disposable domain. Risk score 95/100 → block.",
  "checks": [
    {
      "check": "ipRisk",
      "weight": 45,
      "reason": "datacenter_ip",
      "message": "IP is a datacenter/hosting address, not a residential user",
      "evidence": { "asn": "amazon" }
    },
    {
      "check": "deviceReuse",
      "weight": 15,
      "reason": "device_reuse",
      "message": "This device is linked to 3 accounts, on different networks",
      "evidence": {
        "accountCount": 3,
        "sameAsnAccountCount": 1,
        "resolutionRung": 2,
        "networkCorroborated": false,
        "deterministic": false
      }
    },
    {
      "check": "emailRisk",
      "weight": 35,
      "reason": "disposable_email",
      "message": "Email uses a disposable/temporary domain",
      "evidence": {}
    }
  ],
  "device": {
    "id": "8f1c2ae9d4b7...",          // raw fingerprint. Collides. Debug only
    "resolved_id": "b31f09c7e2a4...", // the identity. Link visits on THIS
    "resolution": "probabilistic",    // no device_token was replayed
    "resolution_rung": 2,             // 1 token · 2 fingerprint+network · 3 neither
    "collision_risk": 0.05,           // measured for android/chrome
    "risk_measured": true,
    "account_count": 3,               // includes fingerprint collisions
    "account_count_same_network": 1,  // the number you can defend
    "distinct_ips": 4,
    "unique": false,
    "connection_type": "datacenter",
    "os": "Android",
    "browser": "Chrome",
    "ja4": true
  },
  // store as a first-party cookie, replay as device_token → rung 1
  "device_token": "kdt_v1.eyJpZCI6IjBmM2E..."
}

Branch on these rather than on the score. Every code is stable and machine-matchable, and every firing carries an evidence object with the raw numbers behind it. No black boxes, no mystery scores.

Network and IP

Where the request came from. These read the caller's IP against offline datasets, so they cost nothing per request and cannot be rate-limited by a third party.

Device and browser integrity

Whether the browser is what it claims to be. Populated by the @kaidn/fp beacon plus the JA4 TLS fingerprint captured at our edge. Each one is high-precision but contributing: none reaches block on its own.

Reuse and velocity

How many accounts or events share one identity, and how fast. Velocity windows are 10 minutes.

Session behaviour over time

What changed mid-session. These need Kaidn.watch() on a logged-in page, which re-beacons the same device every ~60s so a connection change becomes visible.

Email

Whether the address is real, reachable, and one inbox rather than several. See identity.email_canonical on the score response for the dedupe key.

The network graph and your own lists

Facts from outside this event: what other operators have seen, and what you have decided yourself. Your lists always win.

Use these when you want to judge one identifier on its own, without recording an event: validating an address at the form, enriching a support ticket, cleaning a list. Send one field, get a fraud_score (0–100) and the raw intelligence behind it. Keyed and metered like /v1/score; only hashes of PII are stored.

POST /v1/check/email

Body: { "email": "user@domain.com" }

POST /v1/check/ip

Body: { "ip": "3.5.140.1" }

POST /v1/check/phone

Body: { "phone": "+14155550123", "country": "US" } (country optional)

# each lookup is keyed (x-api-key) and counts toward your monthly usage
curl -X POST https://api.kaidn.io/v1/check/email \
  -H "x-api-key: $KAIDN_API_KEY" -H "content-type: application/json" \
  -d '{"email": "x9f2kq@mailinator.com"}'

curl -X POST https://api.kaidn.io/v1/check/ip \
  -H "x-api-key: $KAIDN_API_KEY" -H "content-type: application/json" \
  -d '{"ip": "3.5.140.1"}'

curl -X POST https://api.kaidn.io/v1/check/phone \
  -H "x-api-key: $KAIDN_API_KEY" -H "content-type: application/json" \
  -d '{"phone": "+14155550123"}'

Everything you score is queryable. /v1/events returns newest-first (query: limit ≤ 200, offset, verdict, event). /v1/stats aggregates a time window (query: window_hours, default 24): totals by verdict, average score, and the top reason codes. Raw email addresses are never stored, you get emailHash and emailDomain.

curl "https://api.kaidn.io/v1/events?limit=50&verdict=block" \
  -H "x-api-key: $KAIDN_API_KEY"

curl "https://api.kaidn.io/v1/stats?window_hours=168" \
  -H "x-api-key: $KAIDN_API_KEY"

Make it strict where you bleed and relaxed where you do not. Every weight and threshold is overridable per tenant, and you store only what you change: everything else keeps inheriting Kaidn's tuned defaults. Unknown keys and out-of-range values (outside 0–100) are rejected.

# read current rules (your overrides + effective config)
curl https://api.kaidn.io/v1/config -H "x-api-key: $KAIDN_API_KEY"

# override any weight or threshold, everything else keeps the defaults
curl -X PUT https://api.kaidn.io/v1/config \
  -H "x-api-key: $KAIDN_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "weights": { "emailDisposable": 80 },
    "thresholds": { "review": 30, "block": 60 }
  }'

Defaults, weights

Defaults, thresholds

Blocklisted entities score 100/block instantly; allowlisted ones always pass. Blocks beat allows when both match. Types: ip, email, device, user. Endpoints: GET /v1/lists, POST /v1/lists, DELETE /v1/lists/:id.

# block a device everywhere, instantly (score 100 / block)
curl -X POST https://api.kaidn.io/v1/lists \
  -H "x-api-key: $KAIDN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"list": "block", "type": "device", "value": "fp_c0ffee"}'

# allowlist a trusted user (always passes)
curl -X POST https://api.kaidn.io/v1/lists \
  -H "x-api-key: $KAIDN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"list": "allow", "type": "user", "value": "u_vip_1"}'

curl https://api.kaidn.io/v1/lists -H "x-api-key: $KAIDN_API_KEY"
curl -X DELETE https://api.kaidn.io/v1/lists/42 -H "x-api-key: $KAIDN_API_KEY"

Report the real outcome of an event so scoring sharpens over time. Body: { label, event_id?, entities?, note? } where label is fraud, chargeback, or legit.

• fraud/chargeback with an event_id contributes a confirmedflag to the shared fraud graph, but only if you've opted in, and only for an event you actually scored (proof-of-observation, so you can't flag entities you never saw).
• legit marks a false positive. It's a local suppression only, it stops your account acting on that entity and neverlowers the shared graph's risk. Every legit is written to your audit trail (see below).

# report a real outcome, sharpens scoring. A fraud/chargeback label with an
# event_id contributes a CONFIRMED flag to the shared graph (if you've opted in).
curl -X POST https://api.kaidn.io/v1/label \
  -H "x-api-key: $KAIDN_API_KEY" -H "content-type: application/json" \
  -d '{"label": "chargeback", "event_id": "evt_..."}'

# mark a false positive, LOCAL suppression only, never lowers shared risk
curl -X POST https://api.kaidn.io/v1/label \
  -H "x-api-key: $KAIDN_API_KEY" -H "content-type: application/json" \
  -d '{"label": "legit", "event_id": "evt_..."}'

You are the controller for the end-user data you send us; Kaidn is your processor. These two endpoints exist so you can answer a data-subject request inside the 30 days Art. 12(3) allows, without opening a ticket with us.

POST /v1/subject is access and portability (Art. 15 / 20): pass any of email, phone, ip, device_id, user_id and it returns everything your account holds about that person — scored events, checker-history searches, the device observation timeline and the device profile — with counts and an optional limit (≤ 5000).

POST /v1/forget is erasure (Art. 17). It takes the same identifiers and removes the person from every table that holds them, then stops your account acting on that entity going forward. The two use identical matching, so what /v1/subject shows is exactly what /v1/forget removes. Email matching is alias-aware: erasing a@gmail.com also reaches rows written for a+tag@googlemail.com.

Erasure reclaims the freed pages, so the data leaves the database file rather than merely disappearing from queries.

It is local to your account, it never scrubs the cross-operator graph (that would let a fraud ring erase its own network flags; only Kaidn can clear a shared flag). Because erasing also removes local velocity/device history, every forget, and every legit label, is recorded in a suppression audit so you can spot a socially-engineered erasure.

GET /v1/suppressions returns that audit (newest first, query limit ≤ 500): action (forget/legit), entityType, a one-way valueHash (never raw PII), eventId, and createdMs.

# GDPR erasure, delete a data subject from YOUR account, by any identifier
curl -X POST https://api.kaidn.io/v1/forget \
  -H "x-api-key: $KAIDN_API_KEY" -H "content-type: application/json" \
  -d '{"email": "user@domain.com", "device_id": "fp_..."}'

# review the suppression audit (forgets + false-positive labels; hashes only)
curl https://api.kaidn.io/v1/suppressions -H "x-api-key: $KAIDN_API_KEY"

Error bodies are { "error": "human-readable message" }. Scoring itself fails safe: if the AI narration layer is down you still get a templated reason_text; a score is never blocked on an LLM.

240 requests/minute per API key (429 above that, with standard rate-limit headers). Monthly usage, /v1/score plus the /v1/check/* lookups, scales with your plan; Enterprise gets higher request limits.