API Reference

Password Breach Check

Check passwords against known data breaches using k-anonymity (HIBP protocol)

Check user passwords against billions of known breached credentials without ever transmitting the password itself. Using the k-anonymity model (HIBP protocol), this API lets you enforce password hygiene at registration and login, protecting your users from credential stuffing attacks while preserving their privacy.

k-anonymityHIBP APIzero-knowledge proofSHA-1 prefix matching

Endpoint

POST /v1/password/breach-check

Authentication: Include your API key in the X-API-Key header with every request. All requests go through the API gateway which handles authentication, rate limiting, and usage tracking.

Open Swagger UI (interactive docs)

Request

{
  "password": "P@ssw0rd123"
}

Request Fields

Field	Type	Description
`password`	`string`	Password to check against breach databases

Response

{
  "breached": true,
  "occurrences": 12847,
  "message": "This password has appeared in known data breaches"
}

Response Fields

Field	Type	Description
`breached`	`boolean`	Field value
`occurrences`	`integer`	Field value
`message`	`string`	Field value

Error Codes

Status	Meaning
`200`	Request completed successfully
`400`	Bad request — invalid or missing parameters
`401`	Missing or invalid `X-API-Key` header
`429`	Rate limit exceeded — check `Retry-After` header
`500`	Internal server error

Common Error Scenarios

400 Empty password

Request that triggers this:

{"password": ""}

Error response:

{"type": "/problems/validation-error", "title": "Invalid Password", "status": 400, "detail": "Password cannot be empty"}

How to fix: Ensure the password field is non-empty and contains at least one character.

429 Rate limit exceeded

Request that triggers this:

(after many rapid requests)

Error response:

{"type": "/problems/rate-limit", "title": "Too Many Requests", "status": 429, "detail": "Rate limit exceeded. Try again in 30 seconds"}

How to fix: Implement request throttling. Cache results for the same password to avoid duplicate checks.

Code Examples

curl -X POST /v1/password/breach-check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
  "password": "P@ssw0rd123"
}'

// Node.js (18+) or modern browser
const response = await fetch("/v1/password/breach-check", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "password": "P@ssw0rd123"
}),
});

const data = await response.json();
console.log(response.status, data);

import requests

response = requests.post(
    "/v1/password/breach-check",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
    "password": "P@ssw0rd123"
},
)

print(response.status_code)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "password": "P@ssw0rd123"
}`)
	req, _ := http.NewRequest("POST", "/v1/password/breach-check", body)
	req.Header.Set("X-API-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode)
	fmt.Println(string(data))
}

{
  "name": "password_breach",
  "description": "Check passwords against known data breaches using k-anonymity (HIBP protocol)",
  "inputSchema": {
    "type": "object",
    "properties": {
      "api_key": {"type": "string", "description": "Your Orovai API key"},
      "request": {"type": "object", "description": "Request body"}
    },
    "required": ["api_key", "request"]
  },
  "endpoint": "/v1/password/breach-check",
  "method": "POST",
  "headers": {
    "X-API-Key": "{{api_key}}",
    "Content-Type": "application/json"
  }
}

API Reference