Ratgeber Konto erstellen 🇬🇧 🇩🇪

Entwickler-API

Die Security-Header-API

Ein Endpunkt, eine Dimension: das Security-Ergebnis eines Scans als JSON, ohne den Weg durch das vollständige Report-Schema. Gebaut für CI-Pipelines, Dashboards und Agenturwerkzeuge, die Response-Header regelmäßig prüfen.

 API-Token holen Zur Migration springen

01 Authentifizierung

Ein Bearer-Token je Konto

Jede Anfrage trägt ein API-Token als Bearer-Token im Authorization-Header. Tokens werden auf der API-Token-Seite des Kontos angelegt und widerrufen, und ein Token sieht ausschließlich die Scans seines eigenen Kontos. Der API-Zugang gehört zum Agency-Tarif; ob darunter noch eine leichtere, registrierungsfreie Stufe folgt, ist eine offene Produktfrage und wird hier nicht entschieden.

02 Der Endpunkt

Das Security-Ergebnis eines Scans lesen

Der Endpunkt gibt die Security-Dimension eines fertigen Scans zurück und sonst nichts. Er liest, was der Scan gespeichert hat, und misst nichts eigenes: derselbe Scan-Token antwortet über den vollständigen Report-Endpunkt genauso.

GET /api/v1/scans/{token}/security JSON 

curl -H "Authorization: Bearer $SCAN_API_TOKEN" \ "https://scan.erseni.com/api/v1/scans/8f14e45fceea167a5a36dedd4bea2543/security?locale=en-gb"
{ "schemaVersion": 6, "token": "8f14e45fceea167a5a36dedd4bea2543", "url": "https://example.com/", "status": "finished", "resultAvailable": true, "scanErrorMessage": null, "progressStage": null, "progressPercent": 100, "security": { "dimension": "security", "measured": true, "score": 62, "band": "warn", "rank": "needs_work", "checkSummary": { "passed": 21, "violated": 9, "notChecked": 18, "ran": 30, "total": 48 }, "checks": [ { "key": "strict-transport-security", "state": "passed", "label": "Strict-Transport-Security", "reason": "Enforces HTTPS for every later request." } ], "findings": [ { "code": "security.missing-header.content-security-policy", "severity": "high", "riskLevel": "high", "effort": "medium", "title": "Content-Security-Policy header missing", "detail": "...", "riskStatement": "...", "remediation": "..." } ] } }

03 Einen Scan starten

Zwei Aufrufe, nicht einer

Ein Scan fährt einen echten Browser gegen die Seite, er läuft also asynchron. Der erste Aufruf reiht ihn ein und liefert einen Token, der zweite liest das Ergebnis, sobald der Status auf finished steht. Fragen Sie den Security-Endpunkt ab: solange der Scan läuft, antwortet er mit Status und Fortschritt und einem leeren security-Block.

POST /api/v1/scans 

curl -X POST \ -H "Authorization: Bearer $SCAN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com/"}' \ "https://scan.erseni.com/api/v1/scans"
{ "token": "8f14e45fceea167a5a36dedd4bea2543", "id": 4711, "status": "queued", "statusUrl": "/api/v1/scans/8f14e45fceea167a5a36dedd4bea2543" }

04 Die Antwort lesen

Was die Felder bedeuten

Nichts in der Antwort ist eine Rechtsaussage, und nichts wird der schönen Form zuliebe gefüllt. Eine Dimension, die nie gemessen wurde, kommt als measured false mit einem score von null zurück und nicht als Null-Punkte-Ergebnis.

score

Der Security-Score des Scans von 0 bis 100, oder null, wenn die Dimension nicht gemessen wurde. band ist good, warn, poor oder unknown; rank ist die feinere siebenstufige Skala aus dem Report.

measured

False, wenn der Scan keinen Security-Score trägt. Der Rest des Blocks kann trotzdem gefüllt sein, aber es steht kein Score dahinter.

checkSummary

Wie viele der deklarierten Security-Prüfungen bestanden wurden, verletzt sind und nicht laufen konnten. ran ist passed plus violated, total zählt alle drei. Null bei einem Scan von vor der Prüfbuchführung.

checks

Ein Eintrag je Prüfung mit Schlüssel, Zustand, Bezeichnung und Begründung. Die Liste ist entweder vollständig für die Dimension oder null: eine halbe Liste würde die zufällig benannten Prüfungen als vollen Prüfumfang ausgeben.

findings

Die öffentlichen Security-Befunde des Scans. code ist ein stabiler Fingerabdruck, auf den Sie abbilden können; die vier Texte kommen in der angefragten Sprache.

locale

Optionaler Query-Parameter, en-gb ist der Standard, de-de wird ebenfalls unterstützt. Er wählt die Sprache von Bezeichnungen, Begründungen und Befundtexten. Schlüssel, Codes und Zustände ändern sich mit der Sprache nie.

05 Fehler

Was der Endpunkt antwortet, wenn er nicht antworten kann

Jeder Fehler trägt den HTTP-Status und einen JSON-Body mit errorMessage. Verzweigen Sie über den Statuscode und nicht über den Text: der Wortlaut kann sich ändern, die Codes nicht.

Statuscodes 400 Nicht unterstützte Sprache. Der Query-Parameter locale trägt einen Wert, den wir nicht ausliefern; unterstützt sind en-gb und de-de. Den Parameter wegzulassen ist immer gültig und wählt en-gb. 401 Ungültiges oder fehlendes API-Token. Der Authorization-Header fehlt, ist fehlerhaft aufgebaut, oder das Bearer-Token wurde widerrufen. 403 Der API-Zugang setzt den Agency-Tarif voraus. Das Token hat sich zwar authentifiziert, sein Konto liegt aber nicht auf dem Tarif, der den API-Zugang enthält. 404 Scan nicht gefunden. Den Scan-Token gibt es nicht, oder er gehört zu einem anderen Konto. Beide Fälle antworten absichtlich gleich, damit sich mit einem Token nicht abfragen lässt, welche Scans anderswo existieren. 429 Ratengrenze überschritten, gezählt je Konto und aufrufender IP-Adresse, pro Minute. Die Antwort trägt in der Regel einen Retry-After-Header mit den Sekunden bis zum nächsten Versuch; warten Sie diese Zeit ab, statt sofort erneut zu fragen, und rechnen Sie ohne den Header mit einer Minute.

06 Migration

Von der securityheaders.com-API kommend

Snyk stellt die API von securityheaders.com im April 2026 ein. Die Zuordnung unten ist bewusst wörtlich: wo wir etwas anderes meinen, steht das da, statt unsere Antwort in eine Form zu biegen, die kompatibel aussieht und still etwas anderes berichtet.

Feldzuordnung grade Kein Gegenstück. Wir geben score von 0 bis 100 mit band und rank zurück. Eine Buchstabennote geben wir nicht aus, weil sie aus einem anderen Prüfbestand entstünde und unser A nicht ihr A wäre. missing headers checks-Einträge mit dem Zustand violated, dazu ein findings-Eintrag mit stabilem code. Ein Header, den wir gar nicht lesen konnten, ist notChecked und nicht violated. raw headers Wird nicht zurückgegeben. Ein öffentliches Scan-Ergebnis beschreibt Risiko und gibt nie das Beweismaterial einer fremden Seite heraus. warnings Die Prüfungen information-disclosure, x-xss-protection und cors-configuration, jede mit eigenem Befund. q=<url> POST /api/v1/scans mit dem JSON-Body {"url": "https://example.com/"}. Die Antwort trägt den Scan-Token, den Sie danach lesen. hide=on Kein Gegenstück. Jeder fertige Scan erscheint auf der öffentlichen Liste /scans mit URL, Erstellungszeit und Token. followRedirects Wird immer gefolgt. Beachten Sie: auf einer HSTS-vorbelasteten Domain hebt der Browser HTTP intern auf HTTPS, eine leere Redirect-Kette ist deshalb kein Beleg dafür, dass eine Seite nicht weiterleitet. synchrone Antwort Asynchron. POST reiht den Scan ein und liefert einen Token, GET liest das Ergebnis, sobald der Status finished ist.

07 Mehr als Header

Was wir zusätzlich prüfen

Die Security-Dimension ist breiter als eine Headerliste. Diese Prüfungen kommen mit demselben Aufruf und stehen in checks und findings neben den Header-Prüfungen.

  • TLS-Zertifikat und Transport: Gültigkeit, Hostname-Übereinstimmung, Vertrauenskette, Schlüsselstärke und Signaturverfahren, dazu welche Protokollversionen der Server tatsächlich anbietet, einschließlich der alten TLS-Versionen 1.0 und 1.1.
  • HSTS über die blosse Präsenz hinaus: ob die Richtlinie wirksam ist und ob sie für die Preload-Liste taugt, statt nur ob der Header da ist.
  • CSP-Auslieferung und -Stärke: der erzwingende Header, der Report-Only-Header und eine als Meta-Element ausgelieferte CSP, und wie stark die Direktiven wirklich sind.
  • Cookie-Attribute: Secure, HttpOnly und SameSite, einschließlich des unsicheren Falls SameSite=None.
  • DNS- und Mail-Sicherheit: SPF, DMARC, DNSSEC, CAA, MTA-STS und TLS-RPT.
  • security.txt, Subresource Integrity, Mixed Content und die HTTPS-Weiterleitung.

08 Grenzen

Was wir bewusst nicht tun

Die ehrliche Hälfte des Vergleichs. Nichts davon ist ein Versehen, und jede Zeile sagen wir lieber hier, als dass Sie sie im Betrieb entdecken.

  • Keine Buchstabennote, aus dem Grund, der in der Zuordnung oben steht.
  • Keine Header-Rohwerte und kein Beweismaterial im öffentlichen Ergebnis.
  • Kein aktives Abtasten fremder Infrastruktur: keine Portscans, keine Subdomain-Enumeration, keine Suche nach Admin-Oberflächen oder Backups.
  • OCSP-Stapling wird nicht geprüft. PHP gibt die gestapelte Antwort nicht heraus, die Prüfung wäre also eine Behauptung statt einer Messung.
  • Ein Header-Wert über 512 Zeichen wird gekürzt gespeichert und als notChecked gemeldet. Eine lange, korrekte Content-Security-Policy darf nicht als schwache zurückkommen.
  • Es gelten Ratengrenzen je Konto und aufrufender IP-Adresse, gezählt pro Minute, und ein Scan wird eingereiht statt sofort gefahren.

Bereit zum Anschliessen?

Legen Sie im Konto ein Token an, fahren Sie einen Scan von Hand, um die Form der Antwort zu sehen, und richten Sie dann Ihre Pipeline darauf.

API-Tokens verwalten Tarife ansehen
Aktuelle Scans Ratgeber Preise API Datenschutz Impressum © 2026 Erseni