# Risk assessments (/docs/risk)

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](/docs/webhooks#events).
- `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`](/docs/risk/devices) recognizes it across accounts and spots
  automated ones.
- **Payments**: the card and billing country of a [checkout](/docs/risk/checkout), and cards
  reported before.
- **Your captcha**: the token of your Turnstile or hCaptcha widget, verified with the provider
  ([settings](/docs/risk/settings#captcha)).
- **Content**: what the user wrote (a bio, a message), scored for spam, phishing, malware and fraud
  by an AI model ([content classification](/docs/risk/content)).
- **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](/docs/risk/lists-and-feedback#lists)** and
  **[rules](/docs/risk/rules)**, and your [settings](/docs/risk/settings), including reason weights
  [calibrated](/docs/risk/calibration) from your feedback.

## Assessing a sign-up [#assessing-a-sign-up]

```ts twoslash
import { Coss } from "coss";
const coss = new Coss();
declare const form: { email: string };
declare const request: { ip: string; userAgent: string };
declare function createAccount(email: string): Promise<{ id: string }>;
// ---cut---
const { data: assessment, error } = await coss.risk.assess({
  event: "signup",
  user: { email: form.email },
  ip: request.ip,
  user_agent: request.userAgent,
});

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

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

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

const account = await createAccount(form.email);
```

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.

```ts twoslash
import { Coss } from "coss";
const coss = new Coss();
declare const session: { userId: string; ip: string; userAgent: string };
// ---cut---
const { data } = await coss.risk.assess({
  event: "login",
  user: { id: session.userId },
  ip: session.ip,
  user_agent: session.userAgent,
});
```

Other events are `message`, [`checkout`](/docs/risk/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 [#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 [#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](/docs/spend), 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 [#building-blocks]

Each signal is also available on its own, without an assessment or anything stored:
[email, IP and phone checks](/docs/risk/lookups) and [content classification](/docs/risk/content). And
[rate limiting](/docs/risk/rate-limits) gives your own endpoints coss.com's limiter, with buckets you
define.

## What is stored [#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](/docs/risk/lists-and-feedback#forgetting-users)).

## Tools [#tools]

- **CLI**: [`coss risk`](/docs/cli#risk) `assess`, `assessments`, `feedback` and `lists`.
- **MCP server**: [coding agents](/docs/mcp#tools) 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](/docs/api-reference) shows every operation in Python, Go, Ruby,
  PHP, Java and .NET.
