Zeuslock REST-API-Referenz

Basis-URL und Hosting

Alle Zeuslock-REST-Endpunkte liegen unter einer einzigen Basis-URL:

https://api.zeuslock.ai/v1

Die gemeinsam genutzte Multi-Tenant-API wird in eu-west-3 (Paris) betrieben. Kundendaten, Vorfallsdatensätze und Konfiguration verlassen die EU nie. Wenn Sie die Sovereign Edition einsetzen, ist Ihre Basis-URL eine eigene Subdomain — typischerweise https://api.<tenant>.zeuslock.cloud/v1 — mit exakt denselben Endpunkten, Payloads und Verhaltensweisen. Sie tauschen den Host aus, alles andere bleibt identisch.

Die API spricht ausschließlich JSON über HTTPS. Klartext-HTTP-Anfragen werden bereits am Edge abgewiesen. Jede Verbindung terminiert mit TLS 1.3 und Perfect Forward Secrecy.

Authentifizierung

Es gibt zwei Verfahren. Wählen Sie eines pro Integration; mischen Sie sie nicht innerhalb einer Anfrage.

API-Schlüssel (Server-zu-Server)

API-Schlüssel sind die Standardmethode für Backend-Automatisierung, SIEM-Integrationen, CI/CD-Pipelines und Skripte. Erzeugen Sie einen Schlüssel in der Operator-Konsole unter Einstellungen → API-Schlüssel und übergeben Sie ihn als Bearer-Token:

curl -H "Authorization: Bearer zlsk_live_8f3c..." \
     https://api.zeuslock.ai/v1/incidents

Die Schlüssel tragen das Präfix zlsk_live_ oder zlsk_test_, damit Sie Umgebungen auf einen Blick unterscheiden können. Jeder Schlüssel hat einen expliziten Scope:

• read-only — GET auf Vorfälle, Richtlinien, Detektoren.
• incidents-write — Statusänderungen und Kommentare an Vorfällen.
• admin — Anlegen oder Ändern von Detektoren, Richtlinien und Webhooks.

Schlüssel werden nur einmal beim Anlegen angezeigt. Rotieren Sie sie über die Konsole; der Widerruf greift innerhalb von fünf Sekunden in allen Regionen.

OAuth 2.0 (im Namen des Nutzers)

Für UI-Integrationen, die im Namen eines angemeldeten Operators handeln, nutzen Sie den Standardfluss Authorization Code mit PKCE. Der Authorize-Endpunkt ist https://app.zeuslock.ai/oauth/authorize, der Token-Endpunkt https://api.zeuslock.ai/v1/oauth/token. Die Scopes entsprechen denen der API-Schlüssel. Access-Tokens sind kurzlebig (eine Stunde), Refresh-Tokens rotieren bei jedem Gebrauch.

Rate-Limits

Jeder API-Schlüssel darf 60 Requests pro Sekunde dauerhaft und einen Burst von 600 Req/s erzeugen. Der Bucket füllt sich mit der dauerhaften Rate wieder auf. Drei Header in jeder Antwort erlauben es Ihrem Client, sich selbst zu regulieren:

• X-RateLimit-Limit — dauerhafte Obergrenze für diesen Schlüssel.
• X-RateLimit-Remaining — verbleibende Requests im aktuellen Fenster.
• X-RateLimit-Reset — Epoch-Sekunden, zu denen das Fenster neu beginnt.

Ist der Bucket leer, antwortet die API mit 429 Too Many Requests und dem Header Retry-After (Sekunden). Verwenden Sie exponentielles Backoff; wiederholen Sie nie früher als der angegebene Wert.

Endpunkte im Überblick

Vorfälle

Vorfälle auflisten

Liefert Vorfälle in umgekehrt chronologischer Reihenfolge mit Cursor-Pagination. Das Feld next_cursor ist, wenn vorhanden, opak — reichen Sie es im nächsten Aufruf unverändert zurück.

curl -H "Authorization: Bearer zlsk_live_8f3c..." \
     "https://api.zeuslock.ai/v1/incidents?since=2026-05-01T00:00:00Z&severity=high&limit=100"

import httpx

client = httpx.Client(
    base_url="https://api.zeuslock.ai/v1",
    headers={"Authorization": "Bearer zlsk_live_8f3c..."},
    timeout=30,
)

params = {"since": "2026-05-01T00:00:00Z", "severity": "high", "limit": 100}
while True:
    resp = client.get("/incidents", params=params)
    resp.raise_for_status()
    page = resp.json()
    for incident in page["items"]:
        print(incident["id"], incident["detector"], incident["severity"])
    if not page.get("next_cursor"):
        break
    params["cursor"] = page["next_cursor"]

import fetch from "node-fetch";

const base = "https://api.zeuslock.ai/v1";
const headers = { Authorization: "Bearer zlsk_live_8f3c..." };

let cursor;
do {
  const url = new URL(`${base}/incidents`);
  url.searchParams.set("since", "2026-05-01T00:00:00Z");
  url.searchParams.set("severity", "high");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const res = await fetch(url, { headers });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const page = await res.json();
  for (const i of page.items) console.log(i.id, i.detector, i.severity);
  cursor = page.next_cursor;
} while (cursor);

Einzelnen Vorfall abrufen

GET /v1/incidents/{id} liefert den vollständigen Vorfall einschließlich Prompt-Kontext. Sensible Treffer werden per Default redigiert ausgeliefert (etwa sk-***), mit Offsets, damit Sie die Visualisierung in Ihrem Werkzeug rekonstruieren können.

Vorfallstatus setzen

Bringen Sie einen Vorfall durch Ihren Triage-Workflow. Gültige Werte: open, in_review, resolved und false_positive. Ein Übergang auf false_positive fließt in den nächtlichen Kalibrierungslauf der Detektoren ein.

curl -X POST "https://api.zeuslock.ai/v1/incidents/inc_8c1f.../status" \
     -H "Authorization: Bearer zlsk_live_8f3c..." \
     -H "Content-Type: application/json" \
     -d '{"status":"resolved","comment":"Testschlüssel bestätigt, rotiert."}'

Richtlinien

GET /v1/policies listet alle aktiven Richtlinien auf, inklusive des Modus (monitor, anonymize oder block) je Finding-Typ und der betroffenen Nutzergruppen.

PUT /v1/policies/{id} aktualisiert eine Richtlinie. Hängen Sie ?dry_run=true an, um die Änderung gegen den Traffic der letzten sieben Tage zu validieren, ohne sie tatsächlich anzuwenden — die Antwort enthält den Diff der Vorfälle, die erzeugt, anonymisiert oder geblockt worden wären. So sollten Sie von Monitor zu Block übergehen.

resp = client.put(
    "/policies/pol_credentials",
    params={"dry_run": "true"},
    json={"findings": {"api_key": {"mode": "block"}}},
)
resp.raise_for_status()
print(resp.json()["dry_run_summary"])  # {"would_block": 12, "would_warn": 0, ...}

Detektoren

Eigene Detektoren erfassen organisationsspezifische Identifikatoren — interne Mitarbeiter-IDs, Kundenreferenznummern, eigene Token-Formate. GET /v1/detectors listet sie auf; POST /v1/detectors legt einen neuen an. Jeder Detektor kombiniert eine Regex mit einem oder mehreren Post-Validatoren, um die Präzision hoch zu halten:

• luhn — Prüfsumme im Stil von Kreditkartennummern.
• mod97 — Prüfsumme im Stil von IBANs.
• entropy_gt — verwirft Treffer, deren Shannon-Entropie unter einem Schwellwert (typischerweise 4.5) liegt, um Platzhalter-Strings auszuschließen.

const body = {
  name: "interne_kunden_id",
  regex: "\\bCUST-[A-Z0-9]{10}\\b",
  post_validators: [{ type: "entropy_gt", value: 4.5 }],
  severity: "medium",
  action: "anonymize"
};

const res = await fetch(`${base}/detectors`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify(body)
});
console.log(await res.json());

Synchroner Scan

POST /v1/scan ist das Arbeitspferd für CI/CD-Jobs und Batch-Aufgaben. Senden Sie Rohtext und erhalten Sie die Findings in einem einzigen Round-Trip. Anfragen sind auf 1 MB pro Aufruf begrenzt, mit einem Timeout von 30 Sekunden; für größere Payloads zerlegen Sie client-seitig oder nutzen Sie den asynchronen Batch-Endpunkt (in einem eigenen Dokument beschrieben).

curl -X POST "https://api.zeuslock.ai/v1/scan" \
     -H "Authorization: Bearer zlsk_live_8f3c..." \
     -H "Content-Type: application/json" \
     -d '{"text":"Verbinden mit AKIAIOSFODNN7EXAMPLE und Passwort hunter2","detectors":["api_key","password"]}'

payload = {"text": open("build.log").read(), "detectors": ["api_key", "private_key", "jwt"]}
findings = client.post("/scan", json=payload).json()["findings"]
if findings:
    raise SystemExit(f"Build fehlgeschlagen: {len(findings)} Secrets erkannt")

Fehler

Jede Fehlerantwort nutzt denselben JSON-Umschlag, damit Sie sie einheitlich loggen und routen können:

{
  "error": {
    "code": "invalid_scope",
    "message": "Dieser API-Schlüssel ist nur lesend und kann keine Richtlinien ändern.",
    "request_id": "req_01HX9YJ3K4M5N6P7Q8R9S0T1U2"
  }
}

Geben Sie bei Support-Anfragen stets die request_id an. Gängige HTTP-Codes:

• 400 Bad Request — fehlerhaftes JSON oder fehlendes Pflichtfeld.
• 401 Unauthorized — fehlender oder ungültiger Bearer-Token.
• 403 Forbidden — Token gültig, aber falscher Scope.
• 404 Not Found — unbekannte Ressource oder kein Zugriff in diesem Tenant.
• 422 Unprocessable Entity — Form gültig, Werte aber ungültig (fehlerhafte Regex, unzulässiger Status-Übergang).
• 429 Too Many Requests — halten Sie sich an Retry-After.
• 500 Internal Server Error — sicheres Retry mit exponentiellem Backoff.

Webhooks

Für die Push-Zustellung von Vorfällen an Slack, Splunk HEC, PagerDuty oder Microsoft Sentinel konfigurieren Sie einen Webhook in der Operator-Konsole. Siehe das Webhooks-Dokument für das Payload-Schema und die HMAC-Signaturprüfung.