Skip to content

haveibeenpwned

An unofficial Go client for Troy Hunt's Have I Been Pwned API v3, including the Pwned Passwords k-anonymity range API.

k-anonymity range query
SHA1("password") = 5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8

Only the five highlighted characters ever leave your process — the password itself never does, and responses are padded.

One codebase, four ways to consume it:

Go libraryTyped client with functional options, context support, and honest errors. hibp CLIJSON output for shells, scripts, and CI. Reads passwords from stdin. HTTP JSON APIhibp serve — one shared breach-check service for any language. PHP extensionNative PHP functions compiled from this library via FrankenPHP.

Where to start

  • New here? → Getting Started — install, set up, and configure each form.
  • What can I build with it? → Use Cases — signup password policies, breach monitoring, and more.
  • Integrating the Go library → Library Guide — every method, option, and error type.
  • Calling it over HTTP → HTTP API Reference — every endpoint with request/response examples.
  • Using the CLI → CLI Guide.
  • PHP integration → FrankenPHP Extension.
  • Running the platform → Deployment and IaC — Docker, Compose, Kubernetes, systemd, configuration reference.

Project

Key properties

  • Privacy by design — password checks use k-anonymity: only the first five characters of the password's SHA-1 hash ever leave your process, and responses are padded.
  • No API key needed for password checks, breach catalogue, and data classes. An API key is required only for per-account lookups (breached account, pastes).
  • Well-behaved client — rate-limit aware (Retry-After surfaced, never auto-retried), honest User-Agent, compliant with the HIBP acceptable use policy.
  • Tested without the network — the full suite runs against httptest mocks; CI adds race detection, govulncheck, CodeQL, and secret scanning.

Unofficial client. This project is not affiliated with, endorsed by, or sponsored by Have I Been Pwned or Troy Hunt. Breach and paste data is provided by the Have I Been Pwned service under CC BY 4.0; applications displaying it must visibly credit haveibeenpwned.com. The code is MIT licensed.