Breach search

​

When to use it

• Tell someone whether their address is in a known breach, like the breach search on the orelys.io homepage.
• See what leaked with it: found_types such as pass or phone tell what to change or watch.
• Check an address from a tool whose users have no Orelys account.
• A handful of addresses at a time: it allows 10 searches a minute per address, so it is not for bulk checks.

​

Request

curl https://api.orelys.io/v1/breaches/check \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@example.com" }' \
  --max-time 60

const response = await fetch("https://api.orelys.io/v1/breaches/check", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "jane@example.com" }),
  signal: AbortSignal.timeout(60_000),
});

if (response.status === 429 || response.status === 503) {
  const wait = Number(response.headers.get("Retry-After") ?? "60");
  throw new Error(`Breach search not available, try again in ${wait} s.`);
}
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(error.code);
}

const result = await response.json();
for (const breach of result.breaches) {
  console.log(breach.name, breach.breach_date, breach.found_types.join(", "));
}
if (result.hidden > 0) console.log(`And ${result.hidden} sensitive breach(es) not named publicly.`);

import requests

response = requests.post(
    "https://api.orelys.io/v1/breaches/check",
    json={"email": "jane@example.com"},
    timeout=60,
)
response.raise_for_status()
result = response.json()

for breach in result["breaches"]:
    print(breach["name"], breach["breach_date"], ", ".join(breach["found_types"]))
if result["hidden"]:
    print("And", result["hidden"], "sensitive breach(es) not named publicly.")

​

What you get back

{
  "found": true,
  "count": 1,
  "hidden": 1,
  "breaches": [
    {
      "id": "example-shop-2024",
      "name": "Example Shop",
      "logo_url": "https://api.orelys.io/v1/…",
      "breach_date": "2024-03-02",
      "added_date": "2024-05-17",
      "records": 1204330,
      "data_types": ["email", "pass", "nick", "ip"],
      "sensitive": false,
      "unverified": true,
      "claimed_by": null,
      "summary": "Accounts of the Example Shop forum: email addresses, usernames, passwords and IP addresses.",
      "found_types": ["email", "pass"]
    }
  ]
}

​

Cost and limits

• An IPv6 address counts for its whole /48 network in the limit of 1 at the same time.
• Every search sent counts in the 10 a minute, even one refused for an invalid address.
• The minute is a sliding window. When a limit is reached, wait for Retry-After seconds: until a slot frees up in the minute, or 5 seconds when your search is still running.
• When too many breach searches are running across the API at once (6), a new one answers 503 breach_check_unavailable with Retry-After: 5, whatever your address. Part of those places is kept for the breach search of the orelys.io homepage.
• The whole service has an hourly and a daily cap on breach searches, all callers together. Once it is reached, every breach search answers 503 breach_check_unavailable until the hour or the day ends; Retry-After gives the seconds left.
• Calls made straight to the API (not through orelys.io) share an hourly and a daily part of that cap between them. Once it is used, their breach searches answer 503 breach_check_unavailable until the hour or the day ends, while the orelys.io homepage keeps working.
• One address (an IPv6 address: its /48) can also start only a limited number of new breach searches an hour through the API. Past it, 429 rate_limited until the hour ends; Retry-After gives the seconds left. A search answered from the 60-second memory is refused too: the limit does not depend on the address searched.
• The breach search on the orelys.io homepage uses this same route: searches made there from your address count in the same 10 a minute.

​

Errors

​

Tips

• Give it a full minute. A search keeps its place until our breach-data provider answers, even if your client hangs up. Retrying quickly after a short client timeout only reaches the limit of 1 at the same time.
• Queue, do not fan out. Run one search at a time from one address, and space them to stay within 10 a minute.
• found: true with count: 0 means the address is only in hidden breaches: say how many (hidden), since you cannot say which.
• Show names and summaries as text. They come from third parties: never render them as HTML.
• Call it from your backend. The API does not answer browser calls from other sites, so a web page should send the address to its own server, which calls the API.

​

Reference