Authentifizierung

Schlüssel mitschicken

Der Schlüssel ist eine Art Passwort für Programme. Er geht in jeder Anfrage im Header Authorization mit, nach dem Wort Bearer. Echte Schlüssel beginnen mit sc_live_, danach folgen 32 Zeichen.

Authorization: Bearer sc_live_…

Legen Sie ihn in einer Umgebungsvariable ab und schreiben Sie ihn nicht in den Code. Wir speichern nur einen Hash davon. Den vollen Schlüssel sehen Sie deshalb genau einmal, direkt nach dem Anlegen.

export HULLWISE_API_KEY="sc_live_…"
curl "https://hullwise.co/api/v1/scan?url=example.com" \
  -H "Authorization: Bearer $HULLWISE_API_KEY"

Schlüssel holen

Melden Sie sich an und öffnen Sie im Konto API-Schlüssel. Dort legen Sie neue Schlüssel an und widerrufen alte. Ein widerrufener Schlüssel gilt sofort nicht mehr.

Zum Ausprobieren gibt es den Test-Schlüssel sc_test_demo. Er funktioniert ohne Konto und hat das Limit des kostenlosen Zugangs. Alle, die ihn benutzen, teilen sich dieses Limit, und der Bericht ist immer gekürzt. Für echte Arbeit nehmen Sie Ihren eigenen Schlüssel.

Ohne Schlüssel

Zwei Wege funktionieren ohne Schlüssel. Die REST-API gehört nicht dazu.

• Der MCP-Server unter https://hullwise.co/mcp. Ohne Header gilt das Limit von 20 Checks pro Stunde je IP-Adresse. Mit Schlüssel gilt das Limit Ihres Zugangs. Ein falscher Schlüssel ergibt Status 401. Der Server fällt dann nicht auf den Zugang ohne Schlüssel zurück.
• Der Endpunkt der Startseite GET /api/scan. Er ist für den Browser gedacht und zählt je IP-Adresse oder, wenn Sie angemeldet sind, je Konto. Details in der API-Referenz.

Gekürzter oder vollständiger Bericht

Wie viel im Bericht steht, hängt am Plan des Kontos, zu dem der Schlüssel gehört. Gekürzt wird auf unserem Server, gesperrte Befunde verlassen ihn nicht.

Woran Sie einen gesperrten Befund im JSON erkennen, steht in der API-Referenz.

Limits

Gezählt wird jede Anfrage in einem Fenster von einer Stunde. Das Fenster beginnt mit der ersten Anfrage. Beim MCP-Server zählt jeder Aufruf eines Tools.

Die Limits sollen Missbrauch bremsen. Gezählt wird nicht auf die Anfrage genau. Planen Sie Ihre Last deshalb mit etwas Luft unter dem Limit und fangen Sie Status 429 in jedem Fall ab.

Rate-Limit-Header

Jede Antwort der REST-API auf eine Anfrage mit gültigem Schlüssel nennt, wie viel noch übrig ist.

Ist das Limit erreicht, kommt Status 429 mit dem Code rate_limited. Warten Sie bis zur Zeit in X-RateLimit-Reset und versuchen Sie es dann erneut. Der MCP-Server meldet dasselbe als Tool-Fehler mit dem Text rate_limited. Alle Codes stehen unter Fehler.