Dokumentation
Verwaltungs-API
Mit einem Verwaltungsschlüssel können Ihre eigenen Systeme die API-Schlüssel Ihres Kontos erstellen, gruppieren, begrenzen und widerrufen und über die API auslesen, was sie ausgegeben haben. Ein Modell kann er nicht aufrufen.
Wofür er gedacht ist
Manche Integrationen geben jedem ihrer Kunden, Teams oder Nutzer einen eigenen API-Schlüssel, fassen die Schlüssel jedes Kunden in einer Gruppe zusammen, begrenzen, was eine Gruppe ausgeben darf, und lesen die Kosten pro Schlüssel oder pro Gruppe zurück. Auf der Seite API-Schlüssel genügt das für wenige Schlüssel. Bei mehr erledigt ein Verwaltungsschlüssel dasselbe für ein Skript oder Ihr eigenes Admin-Tool über die API.
Ein Verwaltungsschlüssel sind andere Zugangsdaten als ein API-Schlüssel. Wo ein API-Schlüssel gilt, wird er nicht akzeptiert: Er kann weder /v1/chat/completions noch /v1/messages noch eine andere Modellroute aufrufen. Er funktioniert nur unter /v1/management/, und dort funktioniert ein API-Schlüssel nicht.
Verwaltungsschlüssel erstellen
- Öffnen Sie die Seite API-Schlüssel und gehen Sie ans Ende. Wählen Sie unter „Verwaltungsschlüssel“ die Option „Neuer Verwaltungsschlüssel“. Der Bereich bleibt eingeklappt, bis Sie ihn öffnen.
- Geben Sie dem Schlüssel einen Namen, zum Beispiel „Abrechnungssync“, damit die Seite zeigen kann, welches Programm welche Änderung vorgenommen hat.
- Tragen Sie die Adressen ein, von denen aus er aufgerufen werden darf, eine pro Zeile: eine einzelne Adresse wie 203.0.113.7 oder einen Bereich wie 203.0.113.0/24. Ohne Zulassungsliste kann jeder, der den Schlüssel besitzt, ihn verwenden; der Dialog warnt Sie, wenn Sie die Liste leer lassen.
- Kopieren Sie den Schlüssel, sobald er angezeigt wird. Er wird nur einmal angezeigt: Kunavo speichert nur einen Hash davon.
Ein Konto kann zwei aktive Verwaltungsschlüssel gleichzeitig haben. Widerrufen Sie einen, um Platz für einen anderen zu schaffen.
Aufrufen
Senden Sie den Schlüssel als Bearer-Token an https://api.kunavo.com/v1/management. Verwaltungsschlüssel werden aus einem Browser nicht akzeptiert: Ihre Antworten enthalten keine CORS-Header, daher kann eine Seite auf einer anderen Website sie nicht aufrufen. Ein Schlüssel gehört auf Ihren Server, nie in Frontend-Code.
curl https://api.kunavo.com/v1/management/groups \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"Die Antworten sind JSON. Fehler haben dieselbe Form wie im Rest der API: ein error-Objekt mit message, type, code und, wo es zutrifft, dem fehlerhaften param. Diese Status begegnen Ihnen:
| Status | Bedeutung |
|---|---|
401 | Der Schlüssel fehlt, ist falsch geschrieben oder widerrufen, oder sein Konto ist gesperrt oder in Prüfung. |
403 | Der Schlüssel hat eine IP-Zulassungsliste, und die Anfrage kam von einer Adresse, die nicht darauf steht. |
404 | Die Gruppe oder der Schlüssel existiert nicht, ist gelöscht oder gehört zu einem anderen Konto. Alle drei werden gleich beantwortet, sodass eine ID aus einem anderen Konto nichts verrät. |
409 | Die Änderung steht im Konflikt mit dem Zustand des Kontos: ein bereits verwendeter Gruppenname, ein widerrufener Schlüssel oder das Konto an seiner Obergrenze von 500 aktiven Schlüsseln. |
429 | Dieser Schlüssel hat in der letzten Minute 60 Anfragen gestellt. Der Header Retry-After nennt, wie viele Sekunden zu warten sind. |
Gruppen
GET /v1/management/groups listet die Gruppen des Kontos auf, jeweils mit Monatslimit und Zahl der aktiven Schlüssel. POST erstellt eine, optional mit monthly_limit_usd; ein bereits verwendeter Name ergibt 409. PATCH /v1/management/groups/{id} ändert Name oder Limit: Senden Sie null für kein Limit und 0, um alle Schlüssel der Gruppe zu pausieren, ohne einen zu widerrufen. DELETE entfernt eine Gruppe; ihre Aufrufe behalten auf der Seite Nutzung ihren Namen. Ihre Schlüssel bleiben aktiv und gehören danach zu keiner Gruppe, außer Sie fügen ?revoke_keys=true hinzu, das sie ebenfalls widerruft.
curl https://api.kunavo.com/v1/management/groups \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "CID000001", "monthly_limit_usd": 50}'Schlüssel
GET /v1/management/keys listet Schlüssel auf, die neuesten zuerst. Eine Seite enthält 50 Schlüssel, mit limit bis zu 100. status ist standardmäßig active, oder revoked oder all, und group_id beschränkt die Liste auf eine Gruppe. Ist has_more true, übergeben Sie next_after als after, um die nächste Seite zu lesen. Der Klartext eines Schlüssels wird nie aufgelistet.
POST /v1/management/keys erstellt einen Schlüssel mit Namen und optional group_id, monthly_limit_usd und ip_allowlist. Die Antwort enthält den Klartext einmalig im Feld key. Ein wiederholtes POST erzeugt einen zweiten Schlüssel; listen Sie daher vor einem erneuten Versuch die Schlüssel auf und suchen Sie nach dem Namen.
curl https://api.kunavo.com/v1/management/keys \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "CID000001_user1", "group_id": "GROUP_ID", "monthly_limit_usd": 20}'PATCH /v1/management/keys/{id} ändert Name, Gruppe, Limit oder Zulassungsliste eines Schlüssels; ein group_id von null nimmt ihn aus seiner Gruppe. DELETE widerruft ihn. Einen bereits widerrufenen Schlüssel erneut zu widerrufen ist kein Fehler. Ein widerrufener Schlüssel kann nicht geändert werden.
curl -X DELETE https://api.kunavo.com/v1/management/keys/KEY_ID \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"Nutzung
GET /v1/management/usage meldet die Nutzung des ganzen Kontos über bis zu 90 UTC-Tage, GET /v1/usage die eines einzelnen Schlüssels. group_by akzeptiert jede Mischung aus group, api_key, model und day und hat den Standardwert api_key. Die Zahlen bedeuten dasselbe wie auf der Seite Nutzung: Ein Aufruf zählt zu der Gruppe, in der sein Schlüssel beim Aufruf war, ein fehlgeschlagener Aufruf kostet nichts, und die Summe eines Zeitraums stimmt auf den Cent mit dem CSV-Export derselben Tage überein. group_id und api_key_id beschränken den Bericht auf eine Gruppe oder einen Schlüssel.
curl "https://api.kunavo.com/v1/management/usage?start_date=2026-10-01&end_date=2026-10-31&group_by=group,api_key" \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"end_date nach heute wird als heute gelesen, und die Antwort nennt das verwendete Enddatum.Sicher aufbewahren
- Legen Sie eine Zulassungsliste fest. Ein Schlüssel, der nur von den Adressen Ihres Servers funktioniert, nützt einem Dieb wenig.
- Bewahren Sie den Schlüssel in einem Secret Store auf dem Server auf, auf dem Ihr Tool läuft. Legen Sie ihn nie in einem Browser, einer mobilen App oder einem Repository ab.
- Wenn er offengelegt wurde, widerrufen Sie ihn am Ende der Seite API-Schlüssel oder mit
DELETEauf ihn. Im Widerrufsdialog können Sie auch die Schlüssel widerrufen, die dieser Schlüssel erstellt hat. - Jede Änderung, die der Schlüssel über die API vornimmt, wird auf der Seite API-Schlüssel unter „Verwaltungsschlüssel“ aufgeführt, mit Zeit, Herkunftsadresse und dem Schlüssel, der sie vorgenommen hat: die letzten 50 Änderungen. Änderungen, die von Hand auf dieser Seite vorgenommen werden, werden nicht aufgeführt.
- Ein Schlüssel funktioniert von selbst nicht mehr, wenn sein Konto gesperrt oder in Prüfung gesetzt wird und wenn er widerrufen wird.
Ein Verwaltungsschlüssel darf 60 Anfragen pro Minute stellen. Stellen Sie pro Änderung eine Anfrage und lesen Sie eine Liste seitenweise statt Schlüssel für Schlüssel.
Siehe auch
Gruppen, ihre Monatslimits und die Zählweise ihrer Zahlen werden auf der Seite Schlüsselgruppen erklärt. Die Nutzungszahlen sind dieselben wie auf der Seite Nutzung.