Provisioning-Schlüssel

Ein Provisioning-Schlüssel ermöglicht es Ihrem Backend, Inferenz-API-Schlüssel programmatisch — ohne dass sich jemand in der Konsole anmeldet. Ideal für SaaS-Produkte, die einen Schlüssel pro Endkunde, pro Gerät oder pro CI-Job ausgeben.

Funktionsweise

1. Ein Owner oder Admin erstellt einen Provisioning-Schlüssel in Konsole → Provisioning-Schlüssel. Er trägt das Präfix sk-syn-prov-.
2. Ihr Backend ruft die /api/provisioning/* Endpunkte mit diesem Schlüssel auf, um Inferenzschlüssel zu erstellen (Präfix sk-syn-).
3. Jeder Inferenzschlüssel ist auf denselben Workspace beschränkt und kann ein USD-Ausgabenlimit sowie undurchsichtige metadata tags.
4. Geben Sie die Inferenzschlüssel an Ihre Kunden weiter. Widerrufen Sie jeden einzelnen jederzeit — das Löschen eines Provisioning-Schlüssels beeinflusst nicht die bereits erstellten Inferenzschlüssel.

Authentifizierung

Übergeben Sie den Provisioning-Schlüssel als Bearer-Token. Er funktioniert nur bei /api/provisioning/* — ein Provisioning-Schlüssel kann keine Inferenzaufrufe tätigen, und ein normaler Inferenzschlüssel kann diese Verwaltungs-Endpunkte nicht aufrufen (beide geben 401 wrong_key_kind).

Authorization: Bearer sk-syn-prov-...

Inferenzschlüssel erstellen

POST /api/provisioning/keys

curl https://synthorai.io/api/provisioning/keys \
  -H "Authorization: Bearer sk-syn-prov-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Device abc-123",
    "quota": 5.0,
    "allowed_models": "claude-haiku-4-5",
    "metadata": { "tenant_id": "acme", "device_id": "abc-123" }
  }'

import requests

resp = requests.post(
    "https://synthorai.io/api/provisioning/keys",
    headers={"Authorization": "Bearer sk-syn-prov-..."},
    json={
        "name": "Device abc-123",
        "quota": 5.0,
        "allowed_models": "claude-haiku-4-5",
        "metadata": {"tenant_id": "acme", "device_id": "abc-123"},
    },
)
inference_key = resp.json()["key"]  # full key — shown only once

Die Antwort gibt den vollständigen Schlüssel im key Feld genau einmal. Speichern Sie ihn sofort — er kann später nicht abgerufen werden.

{
  "id": 42,
  "key": "sk-syn-d4f0...e91b",
  "key_prefix": "sk-syn-d4f0...",
  "name": "Device abc-123",
  "kind": "inference",
  "created_via": "provisioning_api",
  "parent_provisioning_id": 7,
  "workspace_id": 11,
  "quota_usd": 5.0,
  "unlimited_quota": false,
  "allowed_models": "claude-haiku-4-5",
  "metadata": { "tenant_id": "acme", "device_id": "abc-123" },
  "created_at": "2026-06-01T12:00:00Z"
}

Inferenzschlüssel auflisten

GET /api/provisioning/keys

Listet jeden Inferenzschlüssel im Workspace auf. Filtern Sie nach jedem Metadatenfeld mit ?metadata.<key>=<value>; mehrere Filter werden mit AND kombiniert.

# all keys
curl https://synthorai.io/api/provisioning/keys \
  -H "Authorization: Bearer sk-syn-prov-..."

# only keys tagged tenant_id=acme
curl "https://synthorai.io/api/provisioning/keys?metadata.tenant_id=acme" \
  -H "Authorization: Bearer sk-syn-prov-..."

Abrufen, aktualisieren & löschen

Adressieren Sie einen einzelnen Inferenzschlüssel über seine numerische id:

• GET /api/provisioning/keys/{id} — einen Schlüssel abrufen.
• PATCH /api/provisioning/keys/{id} — aktualisieren name, quota, status, allowed_models, ip_whitelist, expires_at, include_byok_in_limit, oder metadata. Die Felder kind und Abstammungsfelder können nicht geändert werden.
• DELETE /api/provisioning/keys/{id} — einen Schlüssel widerrufen. Sofort wirksam.

# disable a key (status 2 = disabled)
curl -X PATCH https://synthorai.io/api/provisioning/keys/42 \
  -H "Authorization: Bearer sk-syn-prov-..." \
  -H "Content-Type: application/json" \
  -d '{ "status": 2 }'

# delete a key
curl -X DELETE https://synthorai.io/api/provisioning/keys/42 \
  -H "Authorization: Bearer sk-syn-prov-..."

Kontingente & Ausgabenkontrolle

quota ist ein USD-Limit pro Inferenzschlüssel. Die Nutzung wird nach jeder Anfrage erfasst, daher kann ein Schlüssel sein Limit in einem kurzen Abrechnungsfenster bei hoher Parallelität geringfügig überschreiten — dimensionieren Sie Limits mit einem kleinen Puffer für hochwertige Modelle. Lesen Sie die aktuellen Ausgaben eines Schlüssels aus used_usd in den Auflistungs- / Abrufantworten.

Sie dimensionieren USD-Obergrenzen pro Schlüssel? Der LLM API cost calculator rechnet das erwartete Token-Volumen eines Kunden in einen monatlichen Ausgabenbetrag um, den Sie als quota festlegen können.