How it fits in your flow
1
User submits the sign-up form
Run your usual checks first, such as minimum length. They are free and instant.
2
Your server calls Finowl
Send the password, exactly as typed, to
POST /v1/breaches/password.3
Decide based on count
If
breached is true, ask the user to choose a different password. Otherwise, create the account.Example
Design decisions
Fail open or fail closed?
Fail open or fail closed?
The examples fail open: if Finowl is slow or unavailable, sign up continues. That keeps your conversion rate safe during an outage. If you are protecting high-value accounts, you may prefer to fail closed and ask the user to try again.The examples use a short 5 second timeout because a user is waiting. If the timeout fires, the check may still have been charged.
Should any breach count block the password?
Should any breach count block the password?
Blocking at
count > 0 is the safest choice and what NIST recommends. Some teams warn for low counts and block only above a threshold, for example count >= 10, to reduce friction. Whatever you choose, never tell the user the exact count.Check at login and password change too
Check at login and password change too
Run the same check when users change their password. At login, a breached password is a strong signal to prompt a reset, especially combined with a new device or location.
Write a helpful error message
Write a helpful error message
Explain why, without blaming the user: “This password has appeared in a data breach on another site, so attackers may try it. Please choose a different one.” Suggest a password manager.