Erste Schritte mit der API

In fünf Minuten von null zum ersten Audit-Ergebnis — mit einem API-Zugang, kurzlebigen Tokens und ein paar curl-Befehlen.

1. API-Zugang anlegen

Unter API-Zugang auf „Neuen Zugang anlegen“ klicken, einen Namen vergeben (z. B. „CI-Pipeline“) und die Scopes wählen (für dieses Beispiel scan:read, scan:write und report:read). Sie erhalten eine Client-ID und ein Client-Secret. Das Secret wird nur einmal angezeigt — bewahren Sie es wie ein Passwort auf (Secret-Manager, GitHub Secrets).

2. Access-Token holen

curl -s __APP_DOMAIN__/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=oidc_abc123 \
  -d client_secret=IHR_SECRET

Antwort: {"access_token":"…","token_type":"Bearer","expires_in":3600,"scope":"scan:read scan:write report:read"}. Der Token ist etwa eine Stunde gültig. Holen Sie bei Bedarf einfach einen neuen — es gibt bewusst kein Refresh-Token.

3. Scan starten

curl -s __APP_DOMAIN__/api/audit/start-async \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","preset_sku":"full"}'
# → {"success":true,"job_id":"…"}

Der Scan läuft im Hintergrund. Die Domain muss zu Ihrer Organisation gehören bzw. verifiziert sein (Domain verifizieren).

4. Status abfragen

curl -s __APP_DOMAIN__/api/jobs/JOB_ID -H "Authorization: Bearer $TOKEN"
# → {"success":true,"job":{"status":"completed","progress":100,"scan_id":"…"}}

Wiederholen Sie die Abfrage alle paar Sekunden, bis status completed (oder failed) ist. Alternativ liefert GET /api/jobs/:id/stream den Fortschritt als Server-Sent-Events.

5. Ergebnis und PDF holen

curl -s __APP_DOMAIN__/api/user/scans/SCAN_ID -H "Authorization: Bearer $TOKEN"
curl -s __APP_DOMAIN__/api/user/scans/SCAN_ID/pdf -H "Authorization: Bearer $TOKEN" -o bericht.pdf

Komplettes Skript (bash)

#!/usr/bin/env bash
set -euo pipefail
BASE=__APP_DOMAIN__
TOKEN=$(curl -s $BASE/oauth/token -d grant_type=client_credentials \
  -d client_id="$UA_CLIENT_ID" -d client_secret="$UA_CLIENT_SECRET" | jq -r .access_token)
JOB=$(curl -s $BASE/api/audit/start-async -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"url":"https://example.com","preset_sku":"full"}' | jq -r .job_id)
until [ "$(curl -s $BASE/api/jobs/$JOB -H "Authorization: Bearer $TOKEN" | jq -r .job.status)" != "running" ]; do sleep 5; done
SCAN=$(curl -s $BASE/api/jobs/$JOB -H "Authorization: Bearer $TOKEN" | jq -r .job.scan_id)
curl -s $BASE/api/user/scans/$SCAN/pdf -H "Authorization: Bearer $TOKEN" -o bericht.pdf

Wichtig zu wissen

  • Scopes: Jeder Endpunkt nennt in der API-Referenz die nötigen Scopes. Fehlt einer, antwortet die API mit 403 Missing scope.
  • Kontingent: Scans zählen auf Ihr Paket-Kontingent; ist es aufgebraucht, antwortet die API mit 402.
  • Limits: siehe Rate Limits; bei 429 den Retry-After-Header beachten.
  • Fehler: JSON mit {"success":false,"error":"…"} und passendem HTTP-Status.

Mehr aus der API herausholen

  • Doppelte Starts vermeiden: Senden Sie beim Scan-Start den Header Idempotency-Key: <UUID>. Eine Wiederholung derselben Anfrage (z. B. nach einem Timeout) liefert innerhalb von 24 Stunden dieselbe job_id, ohne einen zweiten Scan zu starten oder Kontingent zu verbrauchen.
  • Kompakte Übersicht für Widgets: GET /api/user/scans/summary?domain=example.com liefert Note, Trend gegenüber dem letzten Audit, Befunde je Bereich und die Links zu Bericht und PDF — ideal für Dashboards und CMS-Plugins.
  • Ereignisse statt Abfragen: Webhooks melden fertige Audits, Notenverschlechterungen und Monitor-Alarme signiert an Ihre URL.
  • Badge für Ihre Website: unter API-Zugang ein Badge anlegen und das Bild einbetten; es zeigt die Note der letzten Prüfung.
  • Code-Audits in GitHub Code Scanning: GET /api/code/scans/:id/sarif liefert die Befunde als SARIF 2.1.0.

Werkzeuge