Skip to content
Open Beta Hansestack is completely free during the current phase. 🐙 Submit feedback on GitHub
Hansestack API Documentation
Integration Workflows

Integration Workflows

Integrating the Hansestack API should take place at critical points in your identity management. Since we are in Public Beta, the architectural design is crucial.

Rule #1: The Fail-Open Principle

Hansestack is an additional security layer. The API must never become a single point of failure for your core business.

Implementing a fail-open mechanism is mandatory:
Configure a strict timeout in your HTTP client (e.g., 500ms to 800ms). If our API does not respond, throws a 5xx error, or if you exceed the rate limit, your system must proceed with the login as if nothing happened. Log the failure internally, but never lock your users out due to an API outage.

The Generic k-Anonymity Check Flow

Regardless of where in your application you implement Hansestack, the fundamental k-Anonymity check process is always identical. This flow guarantees that plaintext passwords never leave your infrastructure.

  1. Local Hashing: The plaintext password is hashed on your system using SHA-1.
  2. Prefix Extraction: The hash is split into a 5-character prefix and a remaining suffix.
  3. API Request: You send only the 5-character prefix to the Hansestack API.
  4. Response: The API returns a JSON object containing a list of all compromised suffixes associated with that prefix.
  5. Local Verification: Your system checks locally if its own suffix is included in the returned list. If it is, the password is considered compromised.
    sequenceDiagram
    participant S as Your System (Frontend/Backend)
    participant H as Hansestack API

    Note over S: SHA-1(Password) = Hash
    Note over S: Split into Prefix (5) + Suffix
    S->>H: GET /v1/prefixes/{prefix}
    H-->>S: List of compromised suffixes
    Note over S: Local Verification:<br/>Is suffix in the list?

Use Cases

Depending on the point in the user lifecycle where the check is performed, different approaches to integration and User Experience (UX) are recommended.

1. During Registration (Sign-Up)

When a new account is created, you proactively prevent insecure passwords from ever entering your database.

Best Practice: Ideally, implement the check directly in the frontend using JavaScript. As soon as the user leaves the password field (onBlur event) or while they type (using debouncing), the check is performed asynchronously.

  • Advantage: The user receives immediate visual feedback ("This password appeared in a known data breach. Please choose another one.") before submitting the form. This reduces friction and frustration.
  • Note: For security reasons, always re-validate the password check in the backend before the record is finally saved.

2. During Login (Sign-In)

During login, you check existing passwords in your database. To minimize server load, the leak check should only be triggered after the email and password have been locally verified as correct in your database.

There are two established architectural approaches here:

Approach A: Synchronous Check (Blocking in the Auth Flow)
The check happens directly during authentication.

  1. Local login is successful.
  2. Leak check against Hansestack is performed.
  3. If the password is compromised, the user is logged in, but the session is temporarily restricted.
  4. The user is immediately redirected to a page forcing a password change ("Forced Password Reset"). They can only use the service after the change.

Approach B: Asynchronous Check (Non-Blocking Background Job)
This approach is optimal if the login flow must not be delayed by external network calls under any circumstances.

  1. The user logs in normally and gains immediate access.
  2. The server asynchronously triggers a background job (e.g., via a message queue or a goroutine) for the leak check.
  3. If a leak is detected, a flag is set in the user database.
  4. On the next page load or via WebSockets, the user receives a persistent warning banner in the dashboard ("Your password has been compromised, please change it") or is notified via email.

3. During Password Change (Password Reset)

Every time a user changes their password—whether voluntarily in the profile settings or via a "forgot password" link—the new password must be checked.

The workflow here is identical to registration: A compromised password is rejected by the system and not saved. The user is prompted to choose a secure alternative.

QuickstartAPI Reference