Risk assessments

Ask coss.com whether a sign-up, login or other event looks like abuse, and why.

Call coss.risk.assess() from your server at the moments abuse happens (a sign-up, a login, a message, a checkout) and act on the decision it returns:

  • allow: go ahead.
  • review: suspicious. Let it through with limits (no free credits, email verification first) or hold it for a person. Reviews show up in the dashboard's Risk page and fire a risk.assessment.review webhook.
  • block: refuse it.

Every assessment comes with a score (0-1) and the reasons behind it, so you can see and explain every decision. coss.com combines:

  • Email signals: syntax, disposable domains, domains that can't receive mail, role accounts (info@), free providers, typos (gmail.con) and domains registered in the last 30 days.
  • IP signals: Tor exit nodes, cloud and hosting networks, networks used by VPNs, private addresses, the network (ASN) and country; VPN exits, proxies and privacy relays by address where coss.com has that data.
  • The browser: coss/device recognizes it across accounts and spots automated ones.
  • Payments: the card and billing country of a checkout, and cards reported before.
  • Your captcha: the token of your Turnstile or hCaptcha widget, verified with the provider (settings).
  • Content: what the user wrote (a bio, a message), scored for spam, phishing, malware and fraud by an AI model (content classification).
  • What this environment has seen: how often the same IP address, subnet, email domain, mailbox, user, card or browser came by in the last hour and day; whether the mailbox or browser already has an account (dots and +tags folded at Gmail and similar); the countries and networks each user logged in from; and identifiers you reported as fraud.
  • Your allow and block lists and rules, and your settings, including reason weights calibrated from your feedback.

Assessing a sign-up

const { : ,  } = await ..({
  : "signup",
  : { : . },
  : .,
  : .,
});

// Fail open: an outage on our side must never lock your users out.
if () .();

if (?. === "block") {
  throw new ("We couldn't create your account.");
}

const  = ?..(() => . === "email.typo");
if () {
  // The one reason worth showing the user: "Did you mean ada@gmail.com?"
  .(.);
}

const  = await (.);

Pass the client's IP address and user agent as your server received them, not your load balancer's (an ip.private reason means it got the proxy's). Don't show reasons to the person being assessed, apart from a typo suggestion: they tell an attacker what to change.

Once the account exists, pass its id with later events (user: { id }). Sign-ups that carry a user id are what duplicate detection compares: a second account for the same mailbox gets duplicate.canonical_mailbox with the first user's id. If you can choose the id before the account is created, pass it with the sign-up itself.

const {  } = await ..({
  : "login",
  : { : . },
  : .,
  : .,
});

Other events are message, checkout and custom (with an event_name such as invite_sent). Velocity is counted per event, so a burst of invitations doesn't count as sign-ups.

Retries and failures

The SDK retries network errors and server errors with the same Idempotency-Key, and a retried assessment returns the first result without counting the event again. Assessments are limited to 100 per second per API key (bursts of 200), or 10 per second (bursts of 50) on the Free plan.

When a signal is unavailable (a slow DNS lookup, missing IP data, a failed classification), the assessment is made without it and the group is listed in degraded; it never fails because of it.

Pricing

Live assessments cost $1.00 per 1,000 assessments for the first 1,000,000; $0.50 per 1,000 assessments from 1,000,001 to 10,000,000; $0.25 per 1,000 assessments beyond 10,000,000. The Free plan includes 10,000 risk assessments a month, Pro 50,000 risk assessments a month and Scale 500,000 risk assessments a month. Decisions that block, retried requests and sandbox assessments are always free, and content in an assessment is part of its price.

An assessment never fails over billing. Past the Free plan's allowance, on a billing hold, or when an API key, member or project is over its budget, it answers as usual, for free, and lists usage_limit in degraded. Your lists, rules, thresholds and the email and IP signals still decide, but velocity, memory of earlier events (duplicates, reported fraud, a user's usual networks), content and address-level IP data are skipped. What it sees is still remembered for later.

Building blocks

Each signal is also available on its own, without an assessment or anything stored: email, IP and phone checks and content classification. And rate limiting gives your own endpoints coss.com's limiter, with buckets you define.

What is stored

Assessments keep the email address, IP address and user agent (never content, only its scores) for 90 days, then only keyed hashes of them; decisions, reasons and signals stay for 1 year. When you delete one of your users, call coss.risk.users.forget(userId) (see Forgetting users).

Tools

  • CLI: coss risk assess, assessments, feedback and lists.
  • MCP server: coding agents get assess_risk, get_risk_assessment, list_risk_assessments, record_risk_feedback, add_risk_list_entry, check_email_risk, check_ip_risk, check_phone_risk and more.
  • Other languages: the API reference shows every operation in Python, Go, Ruby, PHP, Java and .NET.

Last updated