Authentifizierung
Die vokse-API authentifiziert jede Anfrage mit einem Bearer-API-Schlüssel. Schlüssel haben feste Scopes, lassen sich widerrufen und laufen nie stillschweigend ab. Du behältst die volle Kontrolle darüber, worauf eine Integration zugreifen darf.
Der Bearer-Header
Schicke deinen Schlüssel bei jeder Anfrage im Authorization-Header mit. Schlüssel tragen das Präfix vokse_sk_, damit sie in Logs leicht zu erkennen sind (behandle sie wie Passwörter und checke sie nie ein).
Authorization: Bearer vokse_sk_3f8a…Einen Schlüssel erzeugen
Öffne in der vokse-App Einstellungen → API-Schlüssel und erstelle einen Schlüssel. Das Secret siehst du genau einmal, direkt beim Erstellen, kopiere es also sofort. Gib jeder Integration einen eigenen Schlüssel, dann kannst du einen widerrufen, ohne die anderen zu stören.
- Gehe zu Einstellungen → API-Schlüssel.
- Klicke auf „Schlüssel erstellen“ und benenne ihn nach der Integration.
- Wähle die minimalen Scopes, die die Integration wirklich braucht.
- Kopiere das Secret. Es wird nur einmal angezeigt.
Deine Haushalts-ID
Jeder Schlüssel entsteht in genau einem Haushalt und kann nur auf diesen zugreifen. Die API-Routen tragen die Haushalts-ID im Pfad, nachschlagen musst du sie aber selten: Das feste Segment current löst immer auf den Haushalt deines Schlüssels auf. Die echte ID holst du bei Bedarf einmal ab:
curl -H "Authorization: Bearer vokse_sk_3f8a…" \ https://api.vokse.ai/households/currentAlle Beispiele in dieser Referenz verwenden current und laufen deshalb unverändert mit deinem Schlüssel. Lieber explizite IDs? Kopiere deine unter Einstellungen → Mitglieder in der App oder schicke sie im Header X-Household-Id statt im Pfad.
Scopes
Jeder Schlüssel trägt eine Menge von Scopes. Eine Anfrage ist nur zulässig, wenn der Schlüssel den Scope hat, den der Endpunkt verlangt (an jedem Endpunkt als Scope-Badge zu sehen). Scopes gibt es in drei Klassen:
- read:* · Nur-Lese-Zugriff auf eine Ressource (sicher, idempotent).
- write:* · Erstellen, Aktualisieren und Löschen einer Ressource.
- ai:* · KI-Funktionen aufrufen; sie werden auf dein monatliches Kontingent angerechnet.
Ablauf & Rotation
Beim Erstellen kannst du einem Schlüssel ein Ablaufdatum geben. Danach schlagen Anfragen mit API_KEY_EXPIRED fehl. Rotieren heißt: neuen Schlüssel erstellen, ausrollen, alten widerrufen. Erzwungene Ausfallzeit gibt es dabei nicht. Widerrufene Schlüssel funktionieren sofort nicht mehr.