HaveIBeenPwned Authentication: API Keys & Security (2026)

Authentication overview

Authentication for the HaveIBeenPwned (HIBP) API is achieved through the use of API keys. This mechanism allows developers to programmatically access HIBP's services, such as checking email addresses against known data breaches via the Breach API or verifying passwords against the Pwned Passwords database without exposing the plaintext password, thanks to k-anonymity. API keys act as a token that identifies the calling application or user, linking requests to an account and enabling rate limit enforcement and access control. Each API request to a protected endpoint must include a valid API key for successful authorization (HaveIBeenPwned API documentation).

The HIBP API design emphasizes simplicity for integration, providing clear methods for including the API key in request headers. This approach is common in API security for services that require straightforward access management without the complexity of more elaborate protocols like OAuth 2.0, which is typically reserved for delegated authorization scenarios or multi-party identity federation (OAuth 2.0 specification).

Supported authentication methods

HaveIBeenPwned primarily supports API Key authentication. This method is suitable for server-to-server communication or applications where the API key can be securely stored and managed.

The following table outlines the supported authentication method and its characteristics:

API keys are typically passed in the HIBP-API-Key HTTP header for requests to the Breach API (Breach API documentation). For the Pwned Passwords API, an API key is also required for organizational use and higher rate limits, though the core k-anonymity lookup does not strictly require it for unauthenticated, rate-limited access (Pwned Passwords API reference).

Getting your credentials

To obtain an API key for HaveIBeenPwned, follow these steps:

1. Visit the HIBP API page: Navigate to the official HaveIBeenPwned API documentation page.
2. Review pricing and plans: Access to the API, especially for organizational or higher-volume commercial use, requires a subscription. Review the pricing tiers to determine which plan suits your needs. Free access is available for personal/non-commercial use, typically limited to 2,500 requests per month (HIBP API pricing details).
3. Subscribe to a plan: If a paid plan is required, proceed with the subscription process outlined on the HIBP website. This typically involves registering an account and selecting a plan.
4. Generate API Key: Once subscribed or registered for free access, your API key will be made available through your HIBP account dashboard or provided upon subscription confirmation. The exact steps for key generation or retrieval may vary slightly but are generally self-service through the user interface after logging in.
5. Store your API Key securely: Upon obtaining your API key, treat it as sensitive information. It should be stored in a secure manner, such as in environment variables, a dedicated secret management service, or a configuration file that is not committed to version control.

Note that HaveIBeenPwned's API keys are generally long, alphanumeric strings. They are designed to be unique identifiers for your API access.

Authenticated request example

This example demonstrates how to make an authenticated request to the HaveIBeenPwned Breach API using an API key. The key should be passed in the HIBP-API-Key HTTP header.

Requesting all breaches for a specific account (email address):

GET https://haveibeenpwned.com/api/v3/breachedaccount/[email protected]
HIBP-API-Key: YOUR_API_KEY_HERE
User-Agent: YourApplicationName

In this example:

• GET https://haveibeenpwned.com/api/v3/breachedaccount/[email protected] is the endpoint for retrieving breach data for a specific account.
• HIBP-API-Key: YOUR_API_KEY_HERE is the HTTP header where you insert your actual API key. Replace YOUR_API_KEY_HERE with the key obtained from HIBP.
• User-Agent: YourApplicationName is a recommended header that helps HIBP identify your application, which can be useful for debugging or understanding usage patterns.

Using cURL for an authenticated request:

curl -H "HIBP-API-Key: YOUR_API_KEY_HERE" \
     -H "User-Agent: MyCustomApp" \
     "https://haveibeenpwned.com/api/v3/breachedaccount/[email protected]"

This cURL command performs the same request, demonstrating how the headers are included using the -H flag. Successful requests will return a JSON array of breach objects if the account is found in breaches, or a 200 OK with an empty array if not found (HIBP Breach API response formats).

Security best practices

Properly securing your HaveIBeenPwned API keys is essential to prevent unauthorized access, maintain data integrity, and ensure uninterrupted service. Adhering to these best practices will help protect your applications and user data:

1. Treat API Keys as Passwords: API keys grant access to your account and its associated usage limits. Treat them with the same level of confidentiality as you would a sensitive password.
2. Avoid Hardcoding Keys: Never embed API keys directly into your source code. Hardcoding makes keys discoverable in version control systems, even in private repositories, and difficult to rotate. Instead, use environment variables, configuration files, or secret management services. For example, AWS Secrets Manager (AWS Secrets Manager documentation) or Google Secret Manager (Google Cloud Secret Manager overview) can securely store and retrieve API keys at runtime.
3. Use Environment Variables: For server-side applications, storing API keys in environment variables is a common and effective practice. This keeps them out of your codebase and allows for easy rotation without code changes.
4. Implement Secret Management Services: For more complex deployments or microservices architectures, consider using a dedicated secret management service. These services provide centralized, secure storage and controlled access to sensitive credentials, often with features like automatic rotation and auditing.
5. Restrict Key Scope (if applicable): While HIBP API keys typically provide full access to the associated account's API limits, if other APIs you integrate with offer scope restrictions (e.g., read-only access), utilize them to minimize the impact of a compromised key.
6. Rotate Keys Regularly: Periodically rotate your API keys. This practice limits the window of exposure if a key is compromised without your knowledge. Establish a schedule for key rotation and automate the process where possible.
7. Monitor API Usage: Regularly review your API usage logs and billing information for any unusual activity. Spikes in usage or unexpected requests could indicate a compromised key.
8. Secure Client-Side Implementations: Avoid embedding HIBP API keys directly into client-side code (e.g., JavaScript in a web browser or mobile app). If client-side access is necessary, route requests through a secure backend proxy that can add the API key server-side. This prevents the key from being exposed to end-users or attackers.
9. Use HTTPS/TLS: Always ensure that all API communications occur over HTTPS/TLS. This encrypts the data in transit, protecting your API key and other sensitive information from interception. HaveIBeenPwned enforces HTTPS for all API endpoints (HIBP API base URL).
10. Error Handling: Implement robust error handling in your application to gracefully manage authentication failures. Avoid logging API keys in error messages or exposing them through verbose debugging output.

By following these best practices, developers can significantly reduce the risk of API key compromise and ensure the secure and reliable operation of applications that integrate with HaveIBeenPwned.