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

# Check a password

> Find out how often a password appears in known data breaches, without exposing it.

### How the password is protected

1. Finowl hashes the password with SHA-1 in memory.
2. Finowl intelligence searches by the first 5 characters of the hash only (k-anonymity), with padded responses so nothing can be inferred from their size.
3. The exact match is found in memory and its count is returned to you.

The password is never logged, stored or included in the response. SHA-1 is used only for this range lookup, never for storing passwords.

### Good to know

* **Send the exact password.** Do not trim or lowercase it. `Password1` and `password1` are different passwords.
* **Check on submit, not on every keystroke.** Each call uses a credit, and partial passwords are meaningless.
* **`count` measures popularity, not ownership.** It tells you how widely a password has leaked, not which account or breach it came from.
* **Keep passwords out of your logs.** Make sure your HTTP client and error tracker do not record the request body.

<Card title="Guide: block breached passwords at sign up" icon="lock" href="/guides/password-checks-at-signup">
  A complete sign-up flow with sensible thresholds and a fail-open fallback.
</Card>


## OpenAPI

````yaml POST /v1/breaches/password
openapi: 3.1.0
info:
  title: Finowl API
  version: '1.0'
  description: >
    Check emails and passwords against known data breaches, and predict gender
    from

    names, emails and usernames. Every endpoint is a JSON `POST` authenticated
    with a

    bearer API key.
servers:
  - url: https://api.finowl.co
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Breaches
    description: Check whether an email or password appears in known data breaches.
  - name: Gender
    description: >-
      Predict gender from a name, email or username, one at a time or in
      batches.
paths:
  /v1/breaches/password:
    post:
      tags:
        - Breaches
      summary: Check a password
      description: >
        Returns how many times a password appears in known breaches, using
        Finowl intelligence.

        The password is never stored, logged or returned, and it is matched by
        partial hash

        (k-anonymity), so the full password or its full hash is never used in
        the lookup.


        Costs **1 credit**.
      operationId: checkPasswordBreaches
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - password
              properties:
                password:
                  type: string
                  minLength: 1
                  maxLength: 4096
                  description: >-
                    The password to check, exactly as the user typed it.
                    Whitespace and case are preserved.
                  example: P@ssw0rd
      responses:
        '200':
          description: The check completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordBreachResult'
              examples:
                breached:
                  summary: Common password
                  value:
                    breached: true
                    count: 133211
                clean:
                  summary: Not found
                  value:
                    breached: false
                    count: 0
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '502':
          $ref: '#/components/responses/ProviderFailed'
        '503':
          $ref: '#/components/responses/Unavailable'
        '504':
          $ref: '#/components/responses/Unconfirmed'
components:
  schemas:
    PasswordBreachResult:
      type: object
      required:
        - breached
        - count
      properties:
        breached:
          type: boolean
          description: '`true` when the password appears at least once.'
        count:
          type: integer
          minimum: 0
          description: How many times the password appears across known breaches.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
          properties:
            code:
              type: string
              description: >-
                A stable, machine-readable error code. See the Errors page for
                the full list.
              example: invalid_input
  responses:
    InvalidInput:
      description: The request body is not valid. Fix the request before trying again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_input
    Unauthorized:
      description: The API key is missing, malformed or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
    TooManyRequests:
      description: >
        `rate_limited` (too many requests this minute), `quota_exceeded` (not
        enough credits) or

        `provider_rate_limited` (Finowl intelligence is busy). Check the
        `Retry-After` header.
      headers:
        Retry-After:
          description: Seconds to wait before trying again.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
    ProviderFailed:
      description: >-
        Finowl intelligence could not complete the lookup. The request was
        charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: provider_unavailable
    Unavailable:
      description: Finowl intelligence is temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: provider_unavailable
    Unconfirmed:
      description: >-
        Finowl intelligence did not answer in time. The lookup may or may not
        have run, and the request was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: provider_response_unconfirmed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your Finowl API key, for example `finowl_3f9a...`. Create keys in the
        dashboard under **API Keys**.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.