Quickstart: Live Demo, Go Lib & Terminal

To integrate the Hansestack API into your application, you must understand the k-Anonymity concept. You never transmit the password and never transmit the complete hash over the network.

We offer several ways to test this concept immediately and integrate it into your systems.

1. The Live Demo - Try It Instantly in Your Browser

The fastest way to understand our architecture: no install, no setup, right in your browser.

👉 Open the Live Demo at demo.hansestack.de

The demo shows a split-screen setup: a realistic login form on the left, a live Grafana dashboard on the right — the same observability our Caddy plugin ships in production.

The "Aha" moment: Log in with the intentionally compromised password password123. Watch the "Confirmed ATOs" (Account Takeovers) tile on the dashboard flip to red in real time — while the login itself completes normally, thanks to our fail-open architecture. That's decoupled security in action.

Reproduce It Locally with Docker Compose

If you want to inspect the architecture more closely, capture traffic, or use the setup as a base for your own testing, you can spin up the exact same environment locally with Docker Compose.

1. Get an API Key: Register for free in the Portal and generate an API key.
2. Clone the repository:

   git clone https://github.com/hansestack/leakcheck-caddy-demo.git
   cd leakcheck-caddy-demo
3. Configure & Run: Copy .env.example to .env, paste your API key, and start the environment:

   docker compose up

This runs the exact same stack you just tried at demo.hansestack.de locally: Caddy with our plugin, a sample backend, and the Grafana dashboard. You can now run traffic analysis (Wireshark/Proxy) and verify live that only 5-character hashes ever leave your system.

2. Integration Option for Custom Backends: The Official Go Library (hansestack-go)

Not running Caddy in front of your service, and using Go directly in your backend instead? Our official library handles the hashing, parsing of JSON responses, and—most importantly—the fail-open logic completely out of the box.

go get github.com/hansestack/hansestack-go

Minimal Example:

package main

import (
	"context"
	"fmt"
	"time"
	"github.com/hansestack/hansestack-go/leakcheck"
)

func main() {
	// Initializes the client with a strict 500ms fail-open timeout
	client := leakcheck.NewClient(
		"YOUR_API_KEY",
		leakcheck.WithTimeout(500*time.Millisecond),
	)

	leaked, count, err := client.CheckPassword(context.Background(), "Passwort123!")
	if err != nil {
		// FAIL-OPEN: Log the error, but do not block the user!
		// Under the default fail-open policy, err is usually nil,
		// and network errors are logged internally.
		fmt.Printf("API error (proceeding with login): %v\n", err)
	}

	if leaked {
		fmt.Printf("Warning: Password found %d times in known breaches.\n", count)
	} else {
		fmt.Println("Safe: No leak found. Login successful.")
	}
}

Find more details and the source code on GitHub.

3. Integration Option for Custom Backends: Under the Hood with Bash & cURL

If you want to manually build the raw API flow (hash, split, query) for custom clients in Python, Node.js, etc., you can use our raw Bash script as a reference.

We use jq to filter the JSON response locally.

#!/bin/bash

API_KEY="YOUR_API_KEY_HERE"
API_URL="https://api.hansestack.de/leakcheck/v1/prefixes"

echo "Please enter password:"
read -s PASSWORD

HASH=$(echo -n "$PASSWORD" | sha1sum | awk '{print $1}' | tr 'a-z' 'A-Z')
PREFIX=${HASH:0:5}
SUFFIX=${HASH:5}

RESPONSE=$(curl -s -w "\n%{http_code}" -H "X-API-Key: $API_KEY" -H "Accept: application/json" "$API_URL/$PREFIX")
HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
BODY=$(echo "$RESPONSE" | sed '$d')

if [ "$HTTP_CODE" -ne 200 ]; then
    echo "API Error! HTTP Code: $HTTP_CODE"
    exit 1
fi

MATCH=$(echo "$BODY" | jq -r ".suffixes[\"$SUFFIX\"]")

if [ "$MATCH" != "null" ]; then
    echo "⚠️ WARNING: This password was found $MATCH times!"
else
    echo "✅ SAFE: The password did not appear in any leak database."
fi

4. Caddy Reverse Proxy (Zero-Code) - Our Recommendation

The most elegant solution for existing systems, and exactly what you just saw in the live demo: Our native plugin for the Caddy web server. It checks passwords asynchronously right at the infrastructure level, without you having to touch a single line of code in your backend.

For most teams, this is the fastest path to production-grade leak checking — no SDK, no backend redeploy, just one line in your Caddyfile.

Go to Caddy Plugin Documentation →