API & Webhooks

SchlüsselBot sicher in Ihre eigene Software integrieren.

Die Business-API kann Nachrichten erstellen, den Versandstatus prüfen, offene Sendungen zurückziehen und Kontakte verwalten. Webhooks melden wichtige Zustandsänderungen zuverlässig an Ihre Software.

OpenAPI 3.1 herunterladenProduktwissen für KIRechte & Urheberschaft
Granulare RechteJeder Schlüssel bekommt nur die Scopes, die seine Anwendung wirklich benötigt.
Browser-fähigBis zu zehn exakte HTTPS-Origins können je Schlüssel für CORS freigegeben werden.
Zuverlässige EreignisseWebhooks landen zuerst in einer Queue und werden bei Fehlern kontrolliert wiederholt.

Schnellstart

Erzeugen Sie im Konto unter Schnittstelle & Webhooks einen Schlüssel. Er wird genau einmal vollständig angezeigt. SchlüsselBot speichert nur seine Prüfsumme.

curl -X POST https://schluesselbot.de/v1/messages \
  -H "Authorization: Bearer sb_live_XXXXXXXX_…" \
  -H "Idempotency-Key: auftrag-4711-versand-1" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_email": "empfaenger@firma.de",
    "message": "Zugang: kunde42 / T7!kq2wZ",
    "ttl_hours": 48,
    "sender_name": "Kanzlei Weber"
  }'

Für Server-zu-Server-Aufrufe genügt der Bearer-Schlüssel. Externe Browser-Anwendungen brauchen zusätzlich einen beim Schlüssel freigegebenen Origin, zum Beispiel https://portal.firma.de.

Wichtig bei Browser-Anwendungen: CORS verhindert Aufrufe von nicht freigegebenen Websites, macht einen im JavaScript eingebauten API-Schlüssel aber nicht geheim. Verwenden Sie dort einen eng begrenzten Schlüssel und schützen Sie die Anwendung gegen XSS. Für öffentlich ausgeliefertes Frontend-JavaScript ist ein eigenes Backend als Vermittler die sicherere Architektur.

Berechtigungen

ScopeErlaubt
messages:sendNachrichten und bereits clientseitig verschlüsselte Anhänge senden
messages:readStatus einer eigenen API-Sendung abfragen
messages:withdrawEine noch offene eigene Sendung dauerhaft sperren und entfernen
contacts:readEigene Kontakte lesen und durchsuchen
contacts:writeEigene Kontakte anlegen, ändern und löschen

Nachrichten

POST/v1/messagesScope messages:send

/v1/send bleibt als kompatibler Alias bestehen. Verwenden Sie bei automatischen Wiederholungen immer einen eindeutigen Idempotency-Key. Derselbe Schlüssel mit demselben Inhalt liefert 24 Stunden die identische Antwort; anderer Inhalt ergibt HTTP 409.

Zwei Verschlüsselungswege: Mit message erreicht der Klartext kurz den SchlüsselBot-Arbeitsspeicher und wird dort verschlüsselt. Für Anbieterblindheit verschlüsselt Ihre Anwendung selbst, sendet ciphertext und verteilt den Schlüssel getrennt mit delivery_mode: "separate". Ein übermitteltes fragment ermöglicht die automatische E-Mail-Zustellung, erreicht dann aber ebenfalls den Server.
FeldPflichtInhalt
recipient_emailjaEmpfängeradresse
messagealternativKlartext bis 256 KB, serverseitig im Speicher verschlüsselt
ciphertextalternativBase64: 12-Byte-Nonce + AES-256-GCM-Chiffrat + 16-Byte-Tag
fragmentfür automatische Zustellung32-Byte-Schlüssel als 43 Zeichen base64url ohne Padding
attachment_ciphertextneinBereits verschlüsselter Dateicontainer, bis 100 MB Rohdaten
delivery_modeneinautomatic oder separate
ttl_hoursnein1 bis 168, Standard 48
sender_nameneinAnzeigename bis 80 Zeichen
personal_noteneinMail-Notiz bis 500 Zeichen; fremde Links werden entfernt
notify_emailneinE-Mail für den Zustellnachweis nach Abruf
{
  "id": "8f3c…",
  "link": "https://schluesselbot.de/r/8f3c…#kQ2…",
  "expires_at": "2026-08-20T09:00:00+00:00",
  "modus": "vom Server verschlüsselt",
  "delivery": "automatic",
  "mail_sent": true,
  "has_attachment": false
}
GET/v1/messages/{id}Scope messages:read

Liefert ready, consumed, withdrawn, expired oder bei einem vorübergehend nicht prüfbaren Tresor unknown. Ein Ausfall wird nie fälschlich als Abruf gemeldet.

DELETE/v1/messages/{id}Scope messages:withdraw

Sperrt den Vorgang zuerst dauerhaft und entfernt ihn anschließend aus dem Tresor. Scheitert die physische Löschung vorübergehend, bleibt die Sendung trotzdem unöffnungsbar und die Bereinigung wird automatisch wiederholt.

Kontakte

Kontaktnamen und E-Mail-Adressen liegen in der Datenbank AES-256-GCM-verschlüsselt. API-Antworten werden nicht zwischengespeichert.

MethodePfadScopeFunktion
GET/v1/contacts?q=&cursor=&limit=contacts:readSuchen und seitenweise auflisten, höchstens 100 je Seite
POST/v1/contactscontacts:write{"name":"Anna","email":"anna@example.de"}
GET/v1/contacts/{id}contacts:readEinzelnen Kontakt laden
PATCH/v1/contacts/{id}contacts:writeName oder Adresse teilweise ändern
DELETE/v1/contacts/{id}contacts:writeKontakt löschen

Webhooks

Wählbare Ereignisse: created, consumed, withdrawn, expired und delivery_failed. SchlüsselBot speichert jedes Ereignis vor dem ersten Zustellversuch dauerhaft. Erwartet wird HTTP 2xx innerhalb von fünf Sekunden. Bei Fehlern folgen bis zu acht Versuche über ungefähr drei Tage: nach 1 Minute, 5 Minuten, 15 Minuten, 1 Stunde und danach in größeren Abständen.

{
  "api_version": "v1",
  "event_id": "consumed:8f3c…",
  "event": "consumed",
  "zeit": "2026-08-19T10:12:33+00:00",
  "daten": {"id": "8f3c…", "mit_anhang": false}
}
X-SchluesselBot-Event: consumed
X-SchluesselBot-Event-Id: consumed:8f3c…
X-SchluesselBot-Delivery: wd_…
X-SchluesselBot-Signature: sha256=<HMAC-SHA256 des unveränderten Roh-Rumpfs>

Prüfen Sie die Signatur über den unveränderten Request-Body und behandeln Sie event_id idempotent. Das Geheimnis wird beim Anlegen einmal angezeigt und bei SchlüsselBot separat AES-256-GCM-verschlüsselt gespeichert.

// PHP
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $webhookSecret);
if (!hash_equals($expected, $_SERVER['HTTP_X_SCHLUESSELBOT_SIGNATURE'] ?? '')) {
    http_response_code(401); exit;
}

Webhook-Ziele müssen öffentlich erreichbar, HTTPS und ohne Umleitung erreichbar sein. Private, Loopback-, Link-Local-, Dokumentations- und Tailscale/CGNAT-Netze sind gesperrt; die aufgelöste öffentliche IP wird für den tatsächlichen Verbindungsaufbau fest angeheftet.

Fehler und Grenzen