HaveIBeenPwned Getting Started: Account, Keys, First Request (2026)

Getting started overview

Integrating with HaveIBeenPwned (HIBP) involves a sequence of steps to ensure proper authentication and successful API calls. This guide outlines the process from account creation to executing your initial request, focusing on the core HIBP API functionalities for checking email addresses, usernames, and passwords against known data breaches.

The HIBP API provides two primary services: the Breach API, which allows querying for breaches associated with an email address or username, and the Pwned Passwords API, designed for securely checking if a password has appeared in a data breach using a k-anonymity model as described in the official documentation. Both APIs require an API key for authentication, which is obtained after registering for an account.

Here's a quick reference for the getting started process:

Create an account and get keys

To access the HaveIBeenPwned API, you must first create an account and obtain an API key. This key serves as your authentication credential for all API requests.

1. Register for an Account: Navigate to the HaveIBeenPwned API documentation's authentication section, which directs you to the registration process. You will typically provide an email address and create a password.

2. Choose an API Tier: HIBP offers a free tier for personal and non-commercial use, allowing up to 2,500 requests per month. For organizational or higher-volume usage, paid tiers are available, offering increased request limits and additional features as detailed on the pricing page.

3. Generate Your API Key: Once your account is active and you have selected an appropriate tier, log in to your HIBP account dashboard. There, you will find an option to generate your API key. This key is a long alphanumeric string that uniquely identifies your application.

   Important: Treat your API key as a sensitive credential. Do not embed it directly in client-side code, commit it to public repositories, or share it unnecessarily. Best practices for API key management include using environment variables or a secure secret management service as recommended by Google Cloud's API key security guidelines.

Your first request

After obtaining your API key, you can make your first request to the HaveIBeenPwned API. This example demonstrates querying the Breach API for an email address.

Authentication

All requests to the HIBP API require your API key to be passed in the hibp-api-key HTTP header. Additionally, a User-Agent header is required to identify your application.

GET https://haveibeenpwned.com/api/v3/breachedaccount/{account}
Host: haveibeenpwned.com
hibp-api-key: YOUR_API_KEY
User-Agent: YourApplicationName

Example: Checking an Email Address for Breaches

Let's use a placeholder email address to demonstrate a call to the breachedaccount endpoint. Replace YOUR_API_KEY with your actual key and [email protected] with the email you wish to query.

curl -X GET \
  -H "hibp-api-key: YOUR_API_KEY" \
  -H "User-Agent: MyTestApplication" \
  "https://haveibeenpwned.com/api/v3/breachedaccount/[email protected]"

Expected Response

If the email address has been found in any breaches, the API will return a JSON array of breach objects. Each object contains details about a specific data breach, such as the breach name, domain, breach date, and compromised data classes.

[
  {
    "Name": "Adobe",
    "Title": "Adobe",
    "Domain": "adobe.com",
    "BreachDate": "2013-10-04",
    "AddedDate": "2013-12-04T00:00:00Z",
    "ModifiedDate": "2017-12-11T21:51:04Z",
    "PwnCount": 152445165,
    "Description": "In October 2013, 153 million records from Adobe were unlawfully accessed...",
    "DataClasses": [
      "Email addresses",
      "Password hints",
      "Passwords",
      "Usernames"
    ],
    "IsVerified": true,
    "IsFabricated": false,
    "IsSensitive": false,
    "IsRetired": false,
    "IsSpamList": false,
    "LogoPath": "https://haveibeenpwned.com/Content/Images/PwnedLogos/Adobe.png"
  }
]

If the email address is not found in any breaches, the API will return a 200 OK status with an empty JSON array []. A 404 Not Found status indicates that the account was not found in the system, which is generally incorrect for email queries; it's more common for password hashes if the k-anonymity search yields no results.

Pwned Passwords API Example

For checking passwords, the Pwned Passwords API uses a k-anonymity model. You send the first 5 characters of the SHA-1 hash of the password, and the API returns a list of suffix hashes and their breach counts. Your application then compares the full hash locally.

curl -X GET \
  -H "hibp-api-key: YOUR_API_KEY" \
  -H "User-Agent: MyTestApplication" \
  "https://haveibeenpwned.com/api/v3/pwnedpassword/21BD1" # First 5 chars of SHA-1 hash

The response will be a plain text list of hash suffixes and counts:

D016499310A92BEEB10C053E5C3:1
E2F6F79599A4E6C36DD0D8E94E8:2
...

Your application would then compute the full SHA-1 hash of the password, extract the suffix, and check if it exists in the returned list. If it does, the password has been Pwned.

Common next steps

Once you have successfully made your first API call, consider these next steps to further integrate HaveIBeenPwned into your application:

• Error Handling: Implement robust error handling for various HTTP status codes, such as 400 Bad Request, 401 Unauthorized (invalid API key), 403 Forbidden (rate limit exceeded), and 429 Too Many Requests. The HIBP API documentation provides specific error codes.

• Rate Limit Management: Understand and respect the API's rate limits. The API includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers in its responses to help you manage your request volume. Implement exponential backoff or a token bucket algorithm to prevent exceeding limits.

• Pwned Passwords Integration: For password security, integrate the Pwned Passwords API. Ensure you are hashing passwords securely (e.g., using SHA-1, though stronger algorithms like SHA-256 are generally preferred for storage) and only sending the first 5 characters of the hash for the k-anonymity search as demonstrated by Mozilla's Web Crypto API documentation for hashing.

• Data Storage and Caching: Decide on a strategy for storing or caching breach data. While directly querying the API is always an option, for frequently checked accounts, you might consider caching results temporarily while adhering to HIBP's terms of service.

• User Notification: If integrating into an application that serves end-users, design a clear and actionable notification system to inform users if their credentials have been compromised, advising them to change their passwords.

• Monitor API Usage: Regularly check your API usage against your chosen tier's limits to avoid service interruptions. Upgrade your plan if your application's demand increases.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Invalid API Key (401 Unauthorized): Double-check that your hibp-api-key header contains the correct, full API key generated from your account. Ensure there are no leading or trailing spaces.

• Missing User-Agent Header: The HIBP API requires a User-Agent header. Ensure it's present in your request and provides a descriptive name for your application. For example, User-Agent: MyApplication/1.0.

• Rate Limit Exceeded (403 Forbidden or 429 Too Many Requests): If you receive these errors, you've likely exceeded your allocated request limit for your API tier. Wait for the reset period specified in the X-RateLimit-Reset header, or consider upgrading your plan. For initial testing, ensure you are not making too many rapid requests.

• Incorrect Endpoint or Path: Verify that the URL you are calling matches the official HIBP API reference. Pay close attention to capitalization and slashes.

• Network Issues: Ensure your development environment has an active internet connection and no firewall rules are blocking outgoing HTTP requests to haveibeenpwned.com.

• Incorrect Account Format: For the breachedaccount endpoint, ensure the account parameter (email address or username) is correctly URL-encoded if it contains special characters.

• Pwned Passwords Hash Format: When using the Pwned Passwords API, ensure you are sending only the first 5 characters of the SHA-1 hash of the password, and that the hash is in uppercase hexadecimal format.

• Check API Status Page: Occasionally, API services can experience downtime. Check the HaveIBeenPwned homepage or their social channels for any service status updates.