kaidn

Official Python client for Kaidn, the fraud and abuse scoring API.

Send one user action, get back allow, review or block, with the reasons attached.

pip install kaidn

from kaidn import KaidnClient

client = KaidnClient()                       # reads $KAIDN_API_KEY

r = client.score(event="signup", ip=ip, email=email)

if r.blocked:
    raise Denied(r.reason_text)

Zero runtime dependencies. This runs in your signup and checkout path, so every dependency it carried would be one more thing that can break your deploy or turn up in your vulnerability scanner. It uses the standard library and nothing else.

Requires Python 3.9+. Server-side only: it holds your secret key, so never ship it to a browser. The browser half is @kaidn/fp and uses a separate publishable key.

event is the only required field, and the name is yours to choose. Send whatever else you already collect; the answer sharpens as you send more.

r = client.score(
    event="signup",
    user_id=user.id,
    ip=request.remote_addr,
    email=form["email"],
    device_id=form.get("kaidn_device_id"),   # from @kaidn/fp, if installed
)

r.verdict        # "allow" | "review" | "block"
r.reasons        # ["datacenter_ip", "disposable_email"]
r.reason_text    # a sentence you could send to the customer
r.score          # 0-100. Bookkeeping, not a probability: branch on the verdict

Branching, with the three cases people actually use:

if r.blocked:
    return deny()                     # generic message: a specific one teaches the next attempt
if r.needs_review:
    create_account(hold_rewards=True) # they can use the product, they just cannot earn yet
    flag_for_review(r.event_id, r.reason_text)
else:
    create_account()

Every verdict shows its work. key is the config key you would edit to retune that check, so a decision tells you how to change it next time.

for c in r.checks:
    print(c.reason, c.weight, c.key, c.evidence)
    # datacenter_ip 45 datacenterIp {'asn': '16509'}

A browser fingerprint is not a person: on production traffic one iOS Safari fingerprint covers 2.30 different people. So use resolved_id, not id, and weigh it with collision_risk.

d = r.device
if d:
    d.resolved_id                  # the identity. Link visits on this
    d.collision_risk               # measured P(covers more than one person)
    d.account_count                # includes fingerprint collisions
    d.account_count_same_network   # the number you can defend to an angry user

Pass the request's Cookie header and the client replays any token it finds. The identity comes back deterministic, and it survives the network change that splits a fingerprint-derived one in half.

from kaidn import CookieOptions, KaidnClient

client = KaidnClient(cookie=CookieOptions())      # off unless you ask: see below

r = client.score_with_cookie(
    event="login",
    ip=request.remote_addr,
    device_id=form.get("kaidn_device_id"),
    cookies=request.headers.get("Cookie"),
)

if r.set_cookie:
    response.headers["Set-Cookie"] = r.set_cookie

if r.device and r.device.resolution == "deterministic":
    ...   # we have seen THIS browser, not something that hashes like it

Measured on the same browser across two visits, with the IP changed in between:

Your server has to set the cookie, not us. Browsers judge a cookie by the domain that sent Set-Cookie, so one set from your backend on your own domain is genuinely first-party and lasts ~400 days. Anything a vendor sets from its own infrastructure is capped at 7 days on Safari, including the CNAME'd "custom subdomain" setups other vendors ask you to configure. No DNS record, no proxy.

It is off until you pass cookie=, deliberately. Storing something on a visitor's device needs consent or a strict-necessity basis under the ePrivacy Directive, and GDPR legitimate interest does not substitute for it. You are the controller here: the cookie is set by your server, on your domain, and belongs in your cookie policy. The token itself is opaque, carrying a random id, an issue time and a signature scoped to your account.

bob+1@gmail.com, b.o.b@gmail.com and bob@googlemail.com are one mailbox.

if r.identity and User.exists(email_canonical=r.identity.email_canonical):
    return reject("an account already uses this inbox")

No event recorded, useful at the form or when cleaning a list.

client.check.email("x9f2kq@mailinator.com").fraud_score   # 75
client.check.ip("3.5.140.1").report.get("is_datacenter")  # True
client.check.phone("+14155550123", country="US")

Feedback is what sharpens scoring. legit marks your own false positive and never lowers anyone else's risk.

client.label(label="chargeback", event_id=r.event_id)
client.label(label="legit", event_id=r.event_id)

If an endpoint takes an API key, it is a method here. No dropping back to raw HTTP for one call.

Runnable versions of all of it: examples/.

Everything raises KaidnError, with the API's own message.

from kaidn import KaidnError

try:
    r = client.score(event="signup", email=email)
except KaidnError as err:
    if err.status == 429:
        notify_ops("Kaidn quota exhausted")
    raise

Network failures, timeouts, 429s and 5xx are retried automatically (2 extra attempts by default, honouring Retry-After). A 4xx is not: a bad key fails identically the second time, and retrying it just spends quota and delays the error reaching whoever can fix it.

Set a timeout and fail open. A fraud vendor that can take down your signup form is a worse problem than the fraud:

try:
    r = client.score(event="signup", email=email)
except KaidnError:
    r = None          # create the account. Do not let our outage become yours.

Every response keeps what this version does not recognise, so a signal the API ships next week reaches code running the library you installed last year.

r.get("a_field_added_after_this_release")
r.device.get("some_new_signal")
r.extra                                    # everything unrecognised

Requests work the same way: any extra keyword to score() is passed through untouched.

KaidnClient(
    api_key="kdn_live_...",   # default: $KAIDN_API_KEY
    base_url="https://api.kaidn.io",
    timeout=10.0,             # seconds per attempt
    retries=2,                # extra attempts on a transient failure
)

• Docs · Guides · Glossary
• Pricing: 10,000 events a month free, no card

MIT