§ DOCUMENTATION
API-Referenz
REST-API-Endpunkte für die Execlave-Control-Plane.
Basis-URL & Authentifizierung
Basis-URL: https://api.execlave.com# Alle Endpunkte unten sind unter /api/v1 versioniert # Zwei Authentifizierungsmethoden: # 1. API-Schlüssel (empfohlen für SDK/Automatisierung)curl -H "X-API-Key: exe_prod_your_key_here" ... # 2. Logto-JWT (vom Dashboard verwendet)curl -H "Authorization: Bearer <logto_jwt>" ...Alle Endpunkte erfordern eine Authentifizierung. API-Schlüssel sind mit exe_prod_ (Produktion), exe_stg_ (Staging) oder exe_dev_ (Entwicklung) präfixiert. Erstellen Sie Schlüssel unter Einstellungen → API-Schlüssel.
Antwortformat
Erfolg (einzelnes Element)
{ "data": { "id": "uuid", ... } }Erfolg (Liste)
{ "data": [...], "meta": { "total": 42 } }Fehler
{ "error": { "code": "VALIDATION_ERROR", "message": "...", "fields": { ... } } }Agenten
Traces
Richtlinien
Zugriffsgewährungen
Webhooks
Webhook-Signaturen verifizieren
Jede ausgehende Zustellung wird mit HMAC-SHA256 unter Verwendung des Signing-Secrets Ihres Webhooks signiert. Das aktuelle Schema (v2) bindet einen Zeitstempel in die signierte Zeichenkette ein, um Replay-Angriffe zu verhindern; das Legacy-Schema v1 bleibt für laufende Zustellungen während eines Deploys unterstützt.
| Header | Beschreibung |
|---|---|
X-Execlave-Signature | sha256=<hex> — HMAC der signierten Nutzlast. |
X-Execlave-Signature-Version | v1 oder v2. Standard, wenn der Header fehlt: v1. |
X-Execlave-Timestamp | Unix-Sekunden-Zeitstempel des Zeitpunkts, zu dem die Zustellung signiert wurde. Nur bei v2 gesendet. Empfänger sollten Zustellungen außerhalb eines ±5-Minuten-Fensters ablehnen. |
X-Execlave-Idempotency-Key | Stabil pro logischem Ereignis (deterministisch in Org/Ereignis/Body) — derselbe Wert über Wiederholungen hinweg. Verwenden Sie ihn zum Deduplizieren auf der Empfängerseite. |
Verifizierung auf Empfängerseite (Node.js):
const crypto = require('crypto'); function verify(headers, rawBody, secret) { const ts = headers['x-execlave-timestamp']; const sig = headers['x-execlave-signature'].replace('sha256=', ''); const ver = headers['x-execlave-signature-version'] ?? 'v1'; const signedPayload = ver === 'v2' ? `${ts}.${rawBody}` : rawBody; const expected = crypto.createHmac('sha256', secret) .update(signedPayload) .digest('hex'); // Vergleich in konstanter Zeit const a = Buffer.from(expected, 'hex'); const b = Buffer.from(sig, 'hex'); if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) { throw new Error('Invalid webhook signature'); } // v2: ein gleitendes Replay-Fenster erzwingen (±5 Minuten empfohlen) if (ver === 'v2') { const now = Math.floor(Date.now() / 1000); if (Math.abs(now - parseInt(ts, 10)) > 300) { throw new Error('Webhook timestamp outside replay window'); } }} // Idempotenz: über X-Execlave-Idempotency-Key deduplizieren (stabil über Wiederholungen).// Schlüssel mit kurzer TTL (z. B. 24 Std.) persistieren und Duplikate ablehnen.Wichtig: Verifizieren Sie gegen die rohen Anfrage-Bytes, nicht gegen ein neu serialisiertes JSON-Objekt — jede Änderung an Leerzeichen oder Schlüsselreihenfolge bricht den HMAC-Vergleich.
Rate-Limits
| Routengruppe | Limit | Fenster |
|---|---|---|
| Control Plane (Agenten, Richtlinien usw.) | 100 Anfragen | pro Minute |
| Trace-Aufnahme (POST /traces/ingest) | 1.000 Anfragen | pro Minute |
| Richtliniendurchsetzung (POST /policies/enforce) | 10.000 Anfragen | pro Minute |
Limits gelten pro Organisation. Der Durchsetzungs-Bucket ist für den Hot-Path-Verkehr der SDKs dimensioniert und kann pro Deployment über ENFORCEMENT_RATE_LIMIT_PER_MINUTE angepasst werden. Bei einer Ratenbegrenzung gibt die API 429 Too Many Requests mit einem Retry-After-Header zurück. Der Frontend-API-Client und die SDKs handhaben Wiederholungen automatisch mit exponentiellem Backoff.