pip install keverd

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":
    ...

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

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

{
  "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "fingerprint": "kvd_…",
  "visitor_id": "kvd_…",
  "risk_score": 42,
  "recommendation": "allow",
  "action": "allow",
  "reason": ["VPN_DETECTED"],
  "reasons": [
    {
      "code": "VPN_DETECTED",
      "explanation": "The connection appears to route through a VPN.",
      "evidence": {}
    }
  ],
  "score": 0.42,
  "trust_score": 70,
  "reputation_score": null,
  "signals": {},
  "detection": {
    "vpn": { "detected": true, "confidence": 0.72, "method": "ip_mismatch" },
    "riskScore": 0.48,
    "riskLevel": "MEDIUM"
  },
  "smart_signals": {
    "vpn_detected": true,
    "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": []
  }
}

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

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"),
    }

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)

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

from keverd import Keverd, KeverdAPIError, KeverdError, KeverdSignatureError