Check credentials at sign-up, login and password change

Credential Check tells your application whether the credential a user just typed appears in a known leak. You call it from your own sign-up, login and password-change flows. Your backend sends what the user typed, and the answer comes back in the same response, so you can refuse a leaked password or ask for a change on the next screen. Each check is one synchronous POST with a JSON body. There is no job to start and nothing to poll. Each call answers one question:

Has this password appeared in a known leak, under any login?
Has this exact email and password pair leaked together?
Has this pair leaked for one website, such as yours?
Has this email address appeared in a known leak?

Your users’ addresses can be on any domain, public mail providers included. The checks are not limited to domains your organization owns. Availability: every plan with a license in force. Cost: no metered allowance and no per-check daily cap. Each check made with an API key uses one unit of your monthly API Calls allowance, refunded when the response is not 2xx, and counts toward your organization’s per-second rate limit. Every call appears in your API call usage.

Pick a check for each moment

Moment in your flow	Check	When the credential is found, tell the user
A user picks a password at sign-up	Password	”This password has appeared in a data leak. Choose a different one.” Refuse it, or warn before you save it.
A user picks a new password at change or reset	Password	The same message. Refuse the password before you store its hash.
A user logs in with the correct password	Email and password pair	”Your password for this account appeared in a data leak. Change it now.” Finish the sign-in and prompt the change.
The same login, after the pair check finds a match	Pair on your site	The same message. The credential leaked for your site, so require the change before the session continues.
A signed-in user views account or security settings	Email	”This email address appears in known data leaks. Use a password you use nowhere else.” A notice, not a block.

The checks nest, so each narrower check only adds information when the broader one found something:

A pair match is always a password match. The pair check flags only this user’s own leaked pair, not every password someone else leaked.
A site match is always a pair match. Run the site check only after the pair check returns found: true.
An email match says the address leaked. It does not say the user’s current password did. Use it for a notice, and let the pair check decide whether to prompt a change.

The pair, site and email checks need an email address. If your users sign in with a username, or with an AD-style login such as alice@acme.local, use the password check.

Check a new password

Call credential_check_password_compromised when a user picks a password, before you hash and store it. Send the password as password, exactly as the user typed it. Do not hash or trim it. At sign-up the address is not verified yet, so check the password alone. A pair or email result shown to someone who has not proved they own the address tells them whether that address leaked. At a password change the user is signed in. At a reset, the reset link has proven they control the address. In both cases the pair check with their email and the new password is safe too, if you only want to refuse their own leaked pairs.

curl https://client-api.leak.center/api/service/credential_check_password_compromised/ \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"password": "Summer2026!"}'

{
  "found": true,
  "leakCount": 7
}

found: true when at least one leak record holds this password. This is the value your flow acts on.
leakCount: the number of leak records that hold this password, under any login. It counts records, not distinct leaks, and stops at 10,000. A value of 10000 means 10,000 or more.

The rules for the value:

1 to 128 characters. An empty string or a longer value is refused with 400. A password longer than 128 characters cannot be checked. Skip the check for it.
Whitespace is kept. " hunter2 " and "hunter2" are two different passwords. A single space is a valid password.
Matching is case-sensitive. The value is matched as sent, with no wildcards.

Login is the one moment your backend holds an existing user’s password in plain text. Your database holds only hashes. That makes login the moment to run the pair check for accounts that already exist.

Verify the password as usual

Run your own password verification first. On a failed attempt, call nothing.

Run the pair check

Send the email and password the user typed. On found: false, finish the sign-in.

Act on a match

Finish the sign-in and prompt a password change. To require the change when the leak names your site, run the site check next.

Let the user through if a check cannot answer

On an error or a timeout, finish the sign-in without the prompt. See Let the user through when a check cannot answer.

Call credential_check_credentials_compromised with both fields. A request missing either one is refused with 400.

curl https://client-api.leak.center/api/service/credential_check_credentials_compromised/ \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@acme.com", "password": "Summer2026!"}'

{
  "found": true,
  "leakCount": 3
}

A record matches only when it holds both values: the address, without regard to case, and the password, case-sensitively. leakCount stops at 10,000, like the password check. found: true means this user’s current password for this address sits in a leak, next to the address.

Run the pair check only after the password verifies. A check on a failed attempt tells whoever is typing whether their guess is a leaked pair. It also still answers, so a credential-stuffing run against your form would use up your organization’s rate limit and push your real checks into 429.

Check a credential for your own site

The password, pair and email checks take no website. The pair check matches the email and password on any site. To ask whether the pair leaked for your site, call credential_check_leak_search with email, password and website in the body.

curl https://client-api.leak.center/api/service/credential_check_leak_search/ \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@acme.com", "password": "Summer2026!", "website": "acme.com"}'

The response is the leak search envelope: totalElements, page, size and results, in the shape shown under What comes back. Read totalElements. A value greater than 0 means the credential leaked for that site. All three filters must match the same record. A record with no site recorded never matches, so a pair can be found by the pair check and still return 0 here. totalElements stops at 10,000.

Send each host your users sign in on, such as acme.com or login.acme.com. website takes one value of up to 255 characters. It is matched, without regard to case and with no wildcards, against the site recorded on each record. Run one search per host.
Confirm the value matches before you rely on it. Outside the sign-in path, search once with website alone and read the website values that come back. A value in a form your records do not use answers 0, with no error.
A 0 does not clear the user. The pair check already matched, so keep the prompt to change the password.
Leave out password to ask whether any credential for this address leaked for your site. Every field you send narrows the match.
Send no query string. The default page of 10 records is the smallest one. A size below 10 is refused with 400.
Keep results on your server. It carries up to 10 matching records, with the leaked passwords in plain text. Your flow needs only totalElements. Never log or store the response.

Check an email address

Call credential_check_email_compromised for a signed-in user’s verified address, for example on an account or security settings page. Send the address as email.

curl https://client-api.leak.center/api/service/credential_check_email_compromised/ \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@acme.com"}'

{
  "found": true,
  "leakCount": 42,
  "firstSeen": "2019-03-15 10:20:30",
  "lastSeen": "2025-01-10 08:15:00"
}

found: true when at least one leak record holds this address.
leakCount: the number of matching leak records. It stops at 10,000.
firstSeen / lastSeen: when the oldest and the newest matching records were recorded, as YYYY-MM-DD HH:MM:SS. These are recording dates, not breach dates. Both are null when found is false.

{
  "found": false,
  "leakCount": 0,
  "firstSeen": null,
  "lastSeen": null
}

The address is matched without regard to case, so Alice@Acme.com and alice@acme.com get the same answer. Surrounding whitespace is trimmed. The field must be a valid email address. A bare domain or a partial address is refused with 400. An address on a reserved domain such as .local, .test or localhost is refused with 422. An address with an IP-address domain is refused with 400 or 422. AD-style logins such as alice@acme.local fall into this case. Skip the check for those addresses. A found address does not mean your user’s password leaked. Read it next to the pair check: if the email is found but the pair is not, the address leaked, but never with this password.

Act on the answer

Act on found. Any true is enough to refuse a new password or ask for a change. leakCount tells you how widely a value circulates. It is context, not a threshold.
Show results only to the account owner. Run the pair and site checks after a successful login. Show an email result only to the signed-in owner of a verified address. Otherwise your form tells strangers which addresses and passwords are leaked.
Store the outcome, not the input. Keep a flag such as “password change required” on the account. Never store the password you checked or the records that came back.

found: false is a complete answer. If the leak index cannot answer from all of its data, the call fails with 502. You never get a smaller count, or found: false, in its place. An error means unknown, never clean.

Wire the checks into your backend

Call Credential Check from your server, inside the request that handles the form. Your API key authorizes calls as your organization. Anyone who reads it can make the same calls, so it never goes to a browser or a mobile app. Your form posts to your backend as it does today, and your backend calls the API. Keep the API key server-side. Read it from your secret store and send it in the X-API-Key header on every check. Authentication covers API keys. A 401 means the key is invalid, expired or revoked. Alert your team, and do not retry with the same key.

Send the credential in the JSON body

The checks read password from the request body, never from the query string. Send JSON and build it with a JSON encoder, not string concatenation. Quotes, backslashes and non-ASCII characters in a password then reach the API intact.

Set your own timeout

The API waits up to 30 seconds by default for the lookup service before it answers 504. A slow lookup usually ends as a 502 before that. Either way, it is longer than a sign-up or login form should hang. Give the call the wait your form can afford, and treat a timeout as no answer.

Fail open

Decide up front what happens when a check gives no answer. At sign-up, login and password change, let the user continue. An outage on the check then never blocks a sign-up or a sign-in.

Log the status, never the body

Log the status code of a failed check so you can alert on it. Keep the request body and any leak search response out of your HTTP client logs, error trackers and traces. Both hold credentials.

Send the browser only the outcome

The browser needs to know whether to show the warning. It does not need the count or the records.

Never put a password in a URL. A password in the query string is never checked, and URLs are logged far more widely than request bodies.

The helpers below wire the login flow: the pair check, then the site check on a match. Pass in the API key your backend reads from its secret store.

import logging

import requests

API = "https://client-api.leak.center/api/service"
TIMEOUT_SECONDS = 3  # example value. Set the wait your form can afford.

logger = logging.getLogger(__name__)


def credential_check(api_key, endpoint, body):
    """The JSON answer, or None when the check cannot answer."""
    try:
        response = requests.post(
            f"{API}/{endpoint}/",
            json=body,
            headers={"X-API-Key": api_key},
            timeout=TIMEOUT_SECONDS,
        )
        if response.status_code != 200:
            logger.warning("credential check failed: %s %s", endpoint, response.status_code)
            return None
        return response.json()
    except (requests.RequestException, ValueError):
        logger.warning("credential check did not answer: %s", endpoint)
        return None


def leak_status_at_sign_in(api_key, email, password, site="acme.com"):
    """'site', 'pair', 'none', or None when the pair check cannot answer."""
    pair = credential_check(
        api_key,
        "credential_check_credentials_compromised",
        {"email": email, "password": password},
    )
    if pair is None:
        return None
    if not pair.get("found"):
        return "none"
    on_site = credential_check(
        api_key,
        "credential_check_leak_search",
        {"email": email, "password": password, "website": site},
    )
    if on_site is not None and on_site.get("totalElements", 0) > 0:
        return "site"
    return "pair"

const API = "https://client-api.leak.center/api/service";
const TIMEOUT_MS = 3000; // example value. Set the wait your form can afford.

// The JSON answer, or null when the check cannot answer.
async function credentialCheck(apiKey, endpoint, body) {
  try {
    const response = await fetch(`${API}/${endpoint}/`, {
      method: "POST",
      headers: {
        "X-API-Key": apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(TIMEOUT_MS),
    });
    if (response.status !== 200) {
      console.warn(`credential check failed: ${endpoint} ${response.status}`);
      return null;
    }
    return await response.json();
  } catch {
    console.warn(`credential check did not answer: ${endpoint}`);
    return null;
  }
}

// "site", "pair", "none", or null when the pair check cannot answer.
async function leakStatusAtSignIn(apiKey, email, password, site = "acme.com") {
  const pair = await credentialCheck(
    apiKey,
    "credential_check_credentials_compromised",
    { email, password },
  );
  if (pair === null) return null;
  if (!pair.found) return "none";
  const onSite = await credentialCheck(
    apiKey,
    "credential_check_leak_search",
    { email, password, website: site },
  );
  if (onSite !== null && onSite.totalElements > 0) return "site";
  return "pair";
}

In your login handler, after the password verifies: on "site", require a change before the session continues. On "pair", finish the sign-in and prompt a change. On "none", finish the sign-in. On no answer, finish the sign-in without the prompt. The answer is unknown, not clean. The helpers log the endpoint and the status only. They never log the body, which holds the password.

Let the user through when a check cannot answer

A leak check adds a warning to your flow. It should never be the reason a user cannot sign up, sign in or change a password. When a check fails, finish the flow without the warning and log the failure for your team.

Response	What it means	What your flow does
`200`	The check answered from all of its data.	Act on `found`, or on `totalElements` for the site check.
`400` or `422`	The value cannot be checked as sent: an invalid address, a reserved or IP-address domain, or a password over 128 characters.	Let the user continue. Skip the check for this input. A `400` on every call means your request is malformed.
`401`	Your API key is missing, invalid, expired or revoked. If the body says `Invalid or missing service token.`, the API could not authenticate to the lookup service, and your API key is fine.	Let the user continue. Alert your team. Do not retry with the same key. For `Invalid or missing service token.`, treat it like a `502`.
`403`	Your organization has no license in force.	Let the user continue. Alert your team.
`429`	You sent more requests per second than your organization’s rate limit allows.	Let the user continue. Skip checks until `Retry-After` seconds have passed.
`502`	The lookup service or the leak index failed. A slow lookup usually ends here too.	Let the user continue. Do not retry while the user waits. Check again at the next login.
`504`	The API’s wait for the lookup service ran out, 30 seconds by default.	Your own timeout should fire first. Treat it like a `502`.
Your own timeout, or any other error status	No answer.	Treat it like a `502`.

Plan for your volume

Every check is one API call. A sign-in that finds a pair match and then runs the site check makes two. Every call that passes the license check counts toward your organization’s per-second rate limit, failed calls included. That limit is shared with every other call your organization makes. Each of those calls returns X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. They show your current window, usually one second. Read them to space out bursts. Rate limits covers the limits.

You do not need to check on every sign-in. Record when you last checked an account, and check again on a schedule that fits your traffic. Always check a new password at sign-up, password change and reset.

Read the leak records behind an answer

Support and investigation work sometimes needs the records, not just the yes/no. credential_check_leak_search returns the records a check counted. Read and page the records outside the sign-in path. Send the same values you checked, and totalElements matches the leakCount you got, unless new records were indexed in between.

The records hold plaintext passwords. Show them only to the people who investigate, and keep them out of logs.

Run a check

Call the email, password, or pair check. Move on when found is true.

Search with the same values

Send the same email, password, or both in the body. Add website to narrow to one site, and dateFrom or dateTo to narrow by date.

Page through the records

Raise page until you have read totalElements records.

The filters go in the JSON body. Paging goes in the query string.

curl "https://client-api.leak.center/api/service/credential_check_leak_search/?page=0&size=50&sort=createdAt,desc" \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@acme.com", "dateFrom": "2024-01-01"}'

Body filters

Field	Notes
`email`	A valid email address, matched as in the email check.
`password`	1 to 128 characters, matched as in the password check.
`website`	Up to 255 characters, such as `acme.com`. Matched without regard to case against the site recorded on each record.
`dateFrom`	`YYYY-MM-DD`. Earliest date a record was recorded.
`dateTo`	`YYYY-MM-DD`. Latest date a record was recorded.

You need at least one of email, password or website. Dates alone are refused with 400. Every filter you send narrows the result. dateFrom and dateTo each work on their own. Send dates as YYYY-MM-DD. A value longer than 10 characters is refused with 400. An impossible date such as 2024-02-30 is refused with 422.

Query parameters

Parameter	Default	Notes
`page`	`0`	Zero-based page number.
`size`	`10`	Records per page, from 10 to 100.
`sort`	`createdAt,desc`	`field,direction`. Direction is `asc` or `desc`.

Records are ordered by createdAt, newest first by default. sort=createdAt,asc returns the oldest first. The API also accepts leakPublishDate and leakDiscoverDate as the field name, but the order still follows createdAt. Only the direction changes it.

What comes back

{
  "totalElements": 2,
  "page": 0,
  "size": 50,
  "results": [
    {
      "id": "7f3e9a12-4b6c-4d1e-9a85-2c0f6b8d1e47",
      "createdAt": "2025-01-10 08:15:00",
      "email": "alice@acme.com",
      "password": "Summer2026!",
      "fileName": null,
      "leakId": "b2f4e833-2e12-3219-a2b1-84e39d59e194",
      "leakName": "url_login_pass_combolist_2025",
      "leakPublishDate": "2025-01-06",
      "leakDiscoverDate": "2025-01-09",
      "website": "https://acme.com/login"
    },
    {
      "id": "3c81d0e5-92af-4f7b-b6d2-7a4e1f09c3b8",
      "createdAt": "2024-06-02 14:31:09",
      "email": "alice@acme.com",
      "password": "Spring2024!",
      "fileName": null,
      "leakId": "d71c5a60-0b9e-3f42-8e17-5c2a9b3f4d06",
      "leakName": "mixed_combolist_2024_05",
      "leakPublishDate": "2024-05-28",
      "leakDiscoverDate": "2024-06-01",
      "website": "https://mail.acme.com/"
    }
  ]
}

The envelope:

totalElements: the number of matching records. It stops at 10,000, like leakCount.
page / size: the page you asked for and its size.
results: the records on this page.

There is no page count in the response. Divide totalElements by size and round up. Each record:

id: the record’s unique ID.
createdAt: when the record was recorded, as YYYY-MM-DD HH:MM:SS. The date filters and the sort use this field.
email: the leaked login, as an email address or another login name.
password: the leaked password.
website: the site the credential was used on.
leakId / leakName: the leak the record came from. When the leak was published inside a larger collection, these name the collection.
leakPublishDate / leakDiscoverDate: when that leak or collection was published and when it was discovered, as YYYY-MM-DD.
fileName: not populated. It is always null.

leakName and the two leak dates come from the leak catalogue. When the catalogue has no entry for the leak, all three are null and leakId is the record’s own leak ID.

Paging stops at record 10,000. A page whose last record would pass 10,000 is refused with 422. At size=100 the last page you can read is 99. At size=10 it is 999. To reach the rest, flip the sort direction or narrow the date range.

Errors

The API validates your request first, then hands it to the lookup service that reads the leak index. A 400 never reaches the leak index. For what a live flow does with each status, see Let the user through when a check cannot answer.

Status	When	Body
`400`	A field is missing, malformed, or out of range.	One entry per field, for example `{"email": ["Enter a valid email address."]}` or `{"size": ["Ensure this value is less than or equal to 100."]}`. A leak search with no `email`, `password` or `website` returns `{"non_field_errors": ["At least one of email, password or website is required."]}`.
`401`	The API key is missing, invalid, expired, or revoked.	`{"detail": "Authentication credentials were not provided."}` when the `X-API-Key` header is missing. `{"detail": "Invalid or expired API key."}` when the key is invalid, expired, or revoked. `{"detail": "Invalid or missing service token."}` means the API could not authenticate to the lookup service. Your API key is fine, so treat it like a `502`.
`403`	Your organization has no license in force (none, suspended or expired), or its parent organization has none.	`{"detail": "Your license is not active."}`
`422`	The lookup service refused a value the first validation let through: an email address on a reserved domain (`.local`, `.test`, `localhost`) or an IP-address domain such as `alice@[192.0.2.1]`, an impossible date such as `2024-02-30`, a `sort` value it does not accept, or a page past record 10,000.	`{"detail": ...}`. For example, `{"detail": "Invalid sort parameter. Use format: field,direction (e.g. createdAt,desc)"}` or `{"detail": "Page is beyond the searchable range. No more than 10000 records are reachable through pagination."}`. A refused email address or date returns `detail` as a list of field errors.
`429`	You sent more requests per second than your organization’s rate limit allows.	`{"message": "Rate limit exceeded", "retry_after_seconds": 1}`. The `Retry-After` header gives the same wait in seconds.
`502`	The lookup service or the leak index failed or answered with something unusable. You also get it when the lookup service is at capacity or times out on its side, which is how a slow lookup usually ends. Back off before you retry.	`{"detail": "Leak search backend unavailable. Please retry."}` or `{"detail": "The requested service is temporarily unavailable."}`
`504`	The API’s wait for the lookup service ran out. The wait is 30 seconds by default.	`{"detail": "The requested service timed out."}`

Any other error status from the lookup service reaches you unchanged, with its body. Treat it like a 502.

You want	Use
A yes/no for one email address, password, or pair inside your own app	Credential Check (this page)
Free-form Lucene over the account index, with `OR`, `NOT` and field pivots	The ULP feed
Every exposed account on a domain you own, deduplicated and risk-scored	Filtered credentials
The original leaked dump around a credential	Raw Data
The whole capture from an infected machine	Stealer logs

Endpoints

Action	Endpoint
Check a new password	`credential_check_password_compromised`
Check an email and password pair	`credential_check_credentials_compromised`
Check a pair on one site, or read the leak records behind a check	`credential_check_leak_search`
Check an email address	`credential_check_email_compromised`

Get started

Search

Leaked credentials

Assess & report

Monitors

Domain monitoring

Downloads & exports

Changelog

Check credentials at sign-up, login and password change

Pick a check for each moment

Check a new password

Check a credential for your own site

Check an email address

Act on the answer

Wire the checks into your backend

Let the user through when a check cannot answer

Plan for your volume

Read the leak records behind an answer

Body filters

Query parameters

What comes back

Errors

Other credential searches

Endpoints

​Pick a check for each moment

​Check a new password

​Check the pair after a successful login

​Check a credential for your own site

​Check an email address

​Act on the answer

​Wire the checks into your backend

​Let the user through when a check cannot answer

​Plan for your volume

​Read the leak records behind an answer

​Body filters

​Query parameters

​What comes back

​Errors

​Other credential searches

​Endpoints

Pick a check for each moment

Check a new password

Check the pair after a successful login

Check a credential for your own site

Check an email address

Act on the answer

Wire the checks into your backend

Let the user through when a check cannot answer

Plan for your volume

Read the leak records behind an answer

Body filters

Query parameters

What comes back

Errors

Other credential searches

Endpoints