Authentifizierung und API-Schlüssel
Jede Anfrage an die API trägt einen API-Schlüssel im Header Authorization.
curl https://api.speakki.de/v1/assistants \ -H "Authorization: Bearer spk_live_IHR_SCHLUESSEL"Fehlt der Schlüssel oder ist er ungültig, antwortet die API mit Status 401 und dem Code unauthorized.
Schlüssel anlegen
Abschnitt betitelt „Schlüssel anlegen“- Öffnen Sie im Dashboard KI einstellen › Verbindungen › Webhooks & API.
- Klicken Sie unter API-Schlüssel auf Schlüssel anlegen. Geben Sie dem Schlüssel einen Namen, an dem Sie das Programm erkennen, zum Beispiel „Terminsystem“.
- Wählen Sie die Berechtigungen, die das Programm braucht.
- Kopieren Sie den Schlüssel sofort.
Der Schlüssel wird nur einmal angezeigt. SpeakKI speichert ihn nicht im Klartext. Danach sehen Sie im Dashboard nur noch den Anfang, zum Beispiel spk_live_a1B2c3D, und wann der Schlüssel zuletzt verwendet wurde. Geht ein Schlüssel verloren, legen Sie einen neuen an.
Ein Schlüssel beginnt immer mit spk_live_, darauf folgen 40 Zeichen. Je Organisation sind höchstens 10 aktive Schlüssel möglich. Der API-Zugang ist ab dem Tarif Professional enthalten.
Berechtigungen
Abschnitt betitelt „Berechtigungen“Jeder Schlüssel hat feste Berechtigungen. Geben Sie einem Schlüssel nur, was sein Programm braucht.
| Berechtigung | Bezeichnung | Erlaubt |
|---|---|---|
calls:read |
Anrufe lesen | Ausgehende und eingehende Anrufe, Assistenten und Rufnummern abrufen. Dazu gehören auch Gespräche und die Sperrliste. |
calls:write |
Anrufe starten | Ausgehende Anrufe starten und geplante Anrufe abbrechen. |
campaigns:read |
Kampagnen lesen | Kampagnen mit Empfängern und Fortschritt abrufen. |
campaigns:write |
Kampagnen verwalten | Kampagnen anlegen, starten, pausieren und abbrechen. |
contacts:read |
Kontakte lesen | Kontakte der Organisation abrufen. |
appointments:read |
Termine lesen | Termine der Organisation abrufen. |
suppressions:write |
Sperrliste pflegen | Nummern auf die Sperrliste für ausgehende Anrufe setzen und entfernen. |
Fehlt einem Schlüssel die Berechtigung, antwortet die API mit Status 403 und dem Code insufficient_scope. details.required_scope nennt die fehlende Berechtigung. Welche Berechtigung eine Anfrage braucht, steht in der API-Referenz bei jeder Anfrage.
Berechtigungen lassen sich nachträglich nicht ändern. Legen Sie dafür einen neuen Schlüssel an und widerrufen Sie den alten.
Schlüssel widerrufen
Abschnitt betitelt „Schlüssel widerrufen“Klicken Sie im Dashboard an derselben Stelle beim Schlüssel auf Widerrufen. Er gilt sofort nicht mehr, Anfragen damit bekommen 401. Das lässt sich nicht rückgängig machen.
Widerrufen Sie einen Schlüssel, wenn er nicht mehr gebraucht wird, wenn ein Mitarbeiter mit Zugriff ausscheidet oder wenn er an einer falschen Stelle gelandet sein könnte.
Sicherer Umgang
Abschnitt betitelt „Sicherer Umgang“- Verwenden Sie den Schlüssel nur auf Ihrem Server. Im Browser oder in einer App kann ihn jeder auslesen.
- Legen Sie ihn in einer Umgebungsvariable oder einem Geheimnis-Speicher ab, nicht im Quellcode und nicht im Repository.
- Nutzen Sie je Programm einen eigenen Schlüssel. So widerrufen Sie einen, ohne die anderen zu stören.
- Schicken Sie Schlüssel nicht per E-Mail oder Chat.
Rate-Limits
Abschnitt betitelt „Rate-Limits“| Anfragen | Grenze je Schlüssel |
|---|---|
alle Anfragen zusammen, ohne POST /v1/calls |
120 je Minute |
POST /v1/calls |
30 je Minute |
Jede Antwort zeigt den Stand in drei Headern:
| Header | Bedeutung |
|---|---|
x-ratelimit-limit |
Grenze im laufenden Zeitfenster |
x-ratelimit-remaining |
verbleibende Anfragen |
x-ratelimit-reset |
Sekunden, bis das Zeitfenster neu beginnt |
Ist die Grenze erreicht, antwortet die API mit Status 429 und dem Code rate_limited. Der Header retry-after nennt die Sekunden bis zur nächsten möglichen Anfrage. Warten Sie so lange und senden Sie die Anfrage dann erneut.
Für viele Anrufe auf einmal ist eine Kampagne der bessere Weg als viele einzelne Anfragen.