Key-Management-API (Deutsch)

Mit der Key-Management-API legen Ihre eigenen Systeme, zum Beispiel ein ERP, die Inference-API-Keys Ihres Kontos an, ändern sie und widerrufen sie. Üblich ist ein eigener Inference-API-Key je Endkunde. Jeder so angelegte Key gehört zu Ihrem Konto, seine Anfragen werden wie bei jedem anderen Key aus Ihrem Prepaid-Guthaben bezahlt.

English version

1. Management-Key anlegen

Die Key-Management-API nutzt einen eigenen Key-Typ, den Management-Key (llmbase_mk_…). Sie legen ihn nur im Dashboard an, unter API Keys → Management-Keys.

• Erscheint der Abschnitt Management-Keys in Ihrem Dashboard nicht, wenden Sie sich an den Support.
• Das Secret wird genau einmal angezeigt, direkt nach dem Anlegen. Bewahren Sie es wie ein Passwort auf.
• Ein Konto kann bis zu 5 aktive Management-Keys haben.
• Ein Management-Key darf nur /v1/keys aufrufen. Inferenz ist damit nicht möglich: Eine Anfrage an /v1/chat/completions mit einem Management-Key ergibt 403. Inference-API-Keys dürfen /v1/keys nicht aufrufen (403 management_key_required).
• Einen Management-Key widerrufen Sie im Dashboard. Die nächste Anfrage damit ergibt 401 api_key_disabled.

Senden Sie den Management-Key als Bearer-Token:

curl https://api.llmbase.ai/v1/keys \
  -H "Authorization: Bearer $LLMBASE_MANAGEMENT_KEY"

2. Endpunkte

Methode	Pfad	Erfolg	Beschreibung
POST	/v1/keys	201	Inference-API-Key anlegen. Die Antwort enthält das secret, nur hier.
GET	/v1/keys	200	Inference-API-Keys des Kontos auflisten, ohne Secrets.
GET	/v1/keys/{id}	200	Einen Key lesen.
PATCH	/v1/keys/{id}	200	Name, Limits, end_customer_ref oder disabled ändern.
DELETE	/v1/keys/{id}	200	Key widerrufen. Ein wiederholter Aufruf ergibt ebenfalls 200.

Die Liste enthält alle Inference-API-Keys des Kontos, auch die im Dashboard angelegten. Management-Keys erscheinen dort nie.

Key anlegen

curl https://api.llmbase.ai/v1/keys \
  -H "Authorization: Bearer $LLMBASE_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kunde 4711",
    "end_customer_ref": "ERP-4711",
    "monthly_limit_usd_cents": 50000,
    "daily_limit_usd_cents": 5000
  }'

Feld	Typ	Pflicht	Beschreibung
name	String	ja	1 bis 100 Zeichen.
monthly_limit_usd_cents	Integer oder null	nein	Guthabenlimit je UTC-Kalendermonat, in USD-Cent.
daily_limit_usd_cents	Integer oder null	nein	Guthabenlimit je UTC-Tag, in USD-Cent.
end_customer_ref	String oder null	nein	Ihre eigene Referenz, 1 bis 128 Zeichen, eindeutig unter den nicht widerrufenen Keys des Kontos.

Die 201-Antwort ist das Key-Objekt plus "secret": "llmbase_…". Das Secret wird nicht lesbar gespeichert und nie wieder ausgegeben.

Key-Objekt

{
  "id": "key_3f…",
  "object": "api_key",
  "name": "Kunde 4711",
  "end_customer_ref": "ERP-4711",
  "token_prefix": "llmbase_ab12cd",
  "monthly_limit_usd_cents": 50000,
  "daily_limit_usd_cents": 5000,
  "status": "active",
  "created_at": 1762689600,
  "usage": {
    "month": "2026-11",
    "month_spent_usd_cents": 1234,
    "day": "2026-11-09",
    "day_spent_usd_cents": 210
  }
}

• status ist active, disabled oder revoked.
• created_at ist ein Unix-Zeitstempel in Sekunden.
• usage stammt aus der Limitprüfung des Keys. Bei einem Key ganz ohne Limit ist es null. month_spent_usd_cents gibt es, sobald irgendein Limit gesetzt ist, day_spent_usd_cents nur bei gesetztem Tageslimit, sonst ist es null. Der Verbrauch zählt ab dem Setzen des ersten Limits.

Key ändern, deaktivieren oder widerrufen

curl -X PATCH https://api.llmbase.ai/v1/keys/key_3f… \
  -H "Authorization: Bearer $LLMBASE_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"daily_limit_usd_cents": null, "disabled": false}'

• PATCH nimmt name, monthly_limit_usd_cents, daily_limit_usd_cents, end_customer_ref und disabled an. Ein fehlendes Feld bleibt unverändert, null entfernt ein Limit.
• disabled: true sperrt einen Key, disabled: false gibt ihn wieder frei.
• DELETE widerruft einen Key endgültig. Ein widerrufener Key kann nicht wieder aktiviert oder geändert werden (409 api_key_revoked). Im Dashboard widerrufene Keys sind auf dieselbe Weise widerrufen.
• Änderungen gelten ab der nächsten Anfrage. Bereits laufende Anfragen, auch Streams, laufen zu Ende und werden normal abgerechnet.

3. Limits sind optional

Beide Limits sind optional. Ein fehlendes Limit oder null bedeutet, dass der Key in diesem Zeitraum kein Limit hat; er ist dann nur durch Ihr Guthaben und die bestehenden Rate-Limits begrenzt. Ein gesetztes Limit muss ein Integer von 1 bis 1000000 USD-Cent (10.000 USD) sein; 0, negative Werte, Dezimalzahlen und Strings ergeben 400 invalid_limit. Beide Limits gelten; das zuerst erreichte blockiert neue Anfragen: 402 api_key_spend_cap_exceeded beim Monatslimit, 429 api_key_daily_cap_exceeded beim Tageslimit (bis 00:00 UTC).

Hinweis: Dieser Key hat kein Limit. Wir empfehlen, ein Monats- und Tageslimit zu setzen. Guthaben, das über geleakte, kompromittierte oder missbräuchlich genutzte Keys verbraucht wird, erstatten wir nicht.

Das Dashboard zeigt denselben Hinweis bei jedem Key ganz ohne Limit.

4. Pagination

GET /v1/keys liefert die neuesten Keys zuerst:

{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "…" }

• limit: 1 bis 100 Keys je Seite, Standard 100.
• cursor: next_cursor der vorherigen Seite übergeben, um die nächste zu lesen. Der Cursor ist opak; bauen Sie ihn nicht selbst.

5. Grenzen der API

• Rate-Limit: 60 Anfragen pro Minute je Management-Key. Darüber antwortet die API mit 429 rate_limited und Retry-After: 60.
• Anzahl Keys: bis zu 500 nicht widerrufene Inference-API-Keys je Konto. Darüber ergibt POST den Fehler 409 api_key_count_limit_reached.
• Management-Keys: bis zu 5 aktive Management-Keys je Konto.

6. Wiederholungen und verlorene Antworten

Setzen Sie end_customer_ref, damit ein wiederholter POST sicher ist. Ein zweiter Key mit derselben end_customer_ref wird nicht angelegt; die API antwortet mit 409 end_customer_ref_taken und der api_key_id des bestehenden Keys.

Hat Ihr System die 201-Antwort verloren, ist das Secret weg. Widerrufen Sie den Key mit der api_key_id aus der 409 und legen Sie einen neuen an. Ohne end_customer_ref finden Sie den Key per GET /v1/keys über name und created_at.

7. Wenn ein Management-Key kompromittiert ist

Ein Widerruf stoppt nur den Management-Key selbst. Die damit angelegten Inference-API-Keys funktionieren weiter, und ihre Secrets kann kennen, wer den Management-Key hatte.

1. Widerrufen Sie den Management-Key im Dashboard.
2. Widerrufen Sie jeden damit angelegten Inference-API-Key, per DELETE /v1/keys/{id} mit einem neuen Management-Key oder im Dashboard.
3. Wissen Sie nicht, welche Keys er angelegt hat, wenden Sie sich an den Support.

8. Fehler

Fehler haben dasselbe Format wie im Rest der API. param gibt es nur bei 400; die Request-ID steht im Header x-llmbase-request-id.

{
  "error": {
    "message": "monthly_limit_usd_cents must be null or an integer between 1 and 1000000.",
    "type": "invalid_request_error",
    "param": "monthly_limit_usd_cents",
    "code": "invalid_limit"
  }
}

HTTP	code	Bedeutung
400	invalid_limit	Ein Limit ist weder null noch ein Integer von 1 bis 1000000.
400	invalid_request	Ungültiges JSON, unbekanntes Feld, ungültiger name oder ungültiger Cursor.
401	missing_api_key, invalid_api_key, api_key_disabled	Kein Key, unbekannter Key oder widerrufener Management-Key.
403	management_key_required	Ein Inference-API-Key hat /v1/keys aufgerufen.
403	key_management_not_enabled	Key-Management wurde für dieses Konto deaktiviert.
404	api_key_not_found	In Ihrem Konto gibt es keinen Key mit dieser ID.
409	api_key_revoked	Der Key ist widerrufen und kann nicht geändert werden.
409	api_key_count_limit_reached	Das Konto hat die Höchstzahl an Keys erreicht.
409	end_customer_ref_taken	Ein anderer, nicht widerrufener Key nutzt diese end_customer_ref; siehe api_key_id.
429	rate_limited	Mehr als 60 Anfragen pro Minute mit diesem Management-Key.