> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Have I Been Pwned

> Connect Have I Been Pwned (HIBP) so workflows can check accounts, domains, and pastes against known data breaches through the HIBP API - authenticated with an API key.

<Note>
  The Have I Been Pwned integration is in beta.
</Note>

## About Have I Been Pwned

Have I Been Pwned (HIBP) is a data-breach search service. Serval connects to it with an API key so workflows can look up whether an account or domain appears in a known breach, browse the breach and paste catalogs, and reach the rest of the HIBP API on demand - useful for security triage, offboarding checks, and credential-exposure alerts.

**Authentication:**
API key. Serval injects your stored key as the `hibp-api-key` request header on every call, so workflows never handle the key directly. The key comes from [haveibeenpwned.com/API/Key](https://haveibeenpwned.com/API/Key) and requires an active HIBP Pwned subscription.

**Data sync:**
On demand only. There is no background sync and no entity ingestion. Workflows call the HIBP API v3 live when they run.

## Get your credentials

Generate an API key at [haveibeenpwned.com/API/Key](https://haveibeenpwned.com/API/Key). Every key carries a rate limit (requests per minute) set by its subscription tier. Some capabilities need a higher tier: domain search requires the domain to be verified in the HIBP dashboard first, and the stealer-log endpoints require the top Pwned 5 tier.

## Connect in Serval

<Steps>
  <Step title="Open the Have I Been Pwned connect form">
    In Serval, open the Have I Been Pwned integration and start a new connection.
  </Step>

  <Step title="Enter your API Key (required)">
    Paste the API key you generated above.
  </Step>

  <Step title="Save the connection">
    Submit the form. Serval runs the health check below to confirm the key works.
  </Step>
</Steps>

## Verifying the connection

The connection health check reads `/api/v3/subscription/status`, which reports the key's subscription tier and rate limit. A passing check confirms the key is valid and active.

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="A 404 means 'no results', not a failure">
    On lookup endpoints (breached account, breached domain, paste account, and the stealer-log endpoints), HIBP returns **404 when the subject has no results** - that is, the account isn't in any breach. In a workflow, treat a 404 from these endpoints as an empty result rather than an error.
  </Accordion>

  <Accordion title="Rate limits return 429">
    Exceeding your key's per-minute rate limit returns 429 with a `retry-after` header. Reduce polling frequency or batch lookups in scheduled workflows, and check `/api/v3/subscription/status` for your tier's limit.
  </Accordion>

  <Accordion title="Some endpoints need a higher subscription tier">
    Domain search requires the domain to be verified in the HIBP dashboard, and the stealer-log endpoints require the top Pwned 5 tier. If a call fails with an authorization error, confirm your subscription tier covers that endpoint.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Have I Been Pwned integration.