Quickstart

Quickstart: Leak Check in the 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.

The Flow:

Hash: Hash the password locally using SHA-1.
Split: Extract the first 5 characters (prefix).
Query: Send the prefix to the API.
Verify: Check locally if the remainder of the hash (suffix) is included in the API's response.

Hands-on: Bash & cURL

We will test the flow with the password Passwort123!.
To ensure the password remains hidden while typing in the terminal, we use read -s. Afterward, we calculate the hash, isolate the prefix, and query the API.

To filter the JSON response, we use the tool jq (install via apt install jq or brew install jq if necessary).

Copy the following script into your terminal:

#!/bin/bash

# Enter your API key here
API_KEY="YOUR_API_KEY_HERE"
API_URL="https://api.hansestack.de/leakcheck/v1/prefixes"

# 1. Read password securely
echo "Please enter password (will not be displayed):"
read -s PASSWORD

# 2. Calculate SHA-1 hash and convert to uppercase
# The hash for "Passwort123!" is 004C74BE1F2B4EE8D79BFBEFC3690E3CC53D00FA
HASH=$(echo -n "$PASSWORD" | sha1sum | awk '{print $1}' | tr 'a-z' 'A-Z')

# 3. Extract prefix (first 5 chars) and suffix (the rest)
PREFIX=${HASH:0:5}
SUFFIX=${HASH:5}

echo -e "\nHash prefix sent to API: $PREFIX"
echo "Locally searched suffix:     $SUFFIX"

# 4. Query the API
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"
    # FAIL-OPEN: Your application should allow the login to proceed here!
    exit 1
fi

# 5. Local verification using jq
MATCH=$(echo "$BODY" | jq -r ".suffixes[\"$SUFFIX\"]")

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

What happens in the background?

The API responds to the prefix 004C7 (from Passwort123!) with a JSON object containing hundreds of hash endings, all of which share the 004C7 prefix.

Because your terminal knows the rest of your hash is 4BE1F2B4EE8D79BFBEFC3690E3CC53D00FA, jq locally checks whether this exact string exists in the JSON. This allows you to securely verify against billions of hashes without exposing your password.

Integration Workflows