Admin-Schlüssel

Mit einem Admin-Schlüssel verwalten Sie einen Workspace aus Ihrem eigenen Code. Er legt die Inferenzschlüssel für Ihre Kunden oder Geräte an, begrenzt sie und liest Nutzung, Logs und Einstellungen. Modelle aufrufen kann er nicht.

Admin-Schlüssel erstellen

1. Öffnen Sie in der Konsole API-Schlüssel › Admin-Schlüssel und wählen Sie Admin-Schlüssel erstellen. Das können Admins und der Eigentümer des Workspace.
2. Legen Sie fest, wem der Schlüssel gehört und welche Scopes er hat.
3. Kopieren Sie den Schlüssel. Er beginnt mit sk-syn-admin- und wird nur einmal angezeigt.

Scopes

Jeder Scope öffnet einen Teil der Management-API. Ein Schreib-Scope schließt den zugehörigen Lese-Scope ein. Fehlt dem Schlüssel der Scope für eine Anfrage, lautet die Antwort 403 insufficient_scope.

Wem ein Schlüssel gehört

• Ihnen. Der Schlüssel wird deaktiviert, wenn Sie den Workspace verlassen. Bleiben Sie Mitglied, sind aber kein Admin mehr, erhalten Anfragen 403 key_creator_not_authorized.
• Dem Workspace. Der Schlüssel funktioniert weiter, auch wenn die Person, die ihn erstellt hat, den Workspace verlässt oder eine andere Rolle bekommt. Das ist die richtige Wahl für CI und Integrationen. Verlässt diese Person den Workspace, gehen der Schlüssel und die damit erstellten Inferenzschlüssel an den Eigentümer über und funktionieren weiter.

Das legen Sie beim Erstellen fest. Später lässt es sich nicht mehr ändern.

Authentifizierung

Senden Sie den Schlüssel als Bearer-Token. Ein Admin-Schlüssel funktioniert nur an der Management-API: Die Modell-Endpunkte unter /v1/ lehnen ihn ab, und die Management-API lehnt einen Inferenzschlüssel (sk-syn-) mit 401 wrong_key_kind ab.

Authorization: Bearer sk-syn-admin-...

Inferenzschlüssel erstellen

POST /api/v1/keys

curl https://synthorai.io/api/v1/keys \
  -H "Authorization: Bearer sk-syn-admin-..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: device-abc-123" \
  -d '{
    "name": "Device abc-123",
    "limit_usd": 5.0,
    "limit_reset": "monthly",
    "allowed_models": ["claude-haiku-4-5"],
    "metadata": { "tenant_id": "acme", "device_id": "abc-123" }
  }'

import requests

resp = requests.post(
    "https://synthorai.io/api/v1/keys",
    headers={
        "Authorization": "Bearer sk-syn-admin-...",
        "Idempotency-Key": "device-abc-123",
    },
    json={
        "name": "Device abc-123",
        "limit_usd": 5.0,
        "limit_reset": "monthly",
        "allowed_models": ["claude-haiku-4-5"],
        "metadata": {"tenant_id": "acme", "device_id": "abc-123"},
    },
)
inference_key = resp.json()["data"]["key"]  # full key - shown only once

Die Antwort enthält den vollständigen Schlüssel im Feld key, und zwar nur dieses eine Mal. Speichern Sie ihn sofort: Spätere Abfragen liefern nur noch key_prefix.

{
  "data": {
    "id": 42,
    "key": "sk-syn-d4f0...e91b",
    "key_prefix": "sk-syn-d4f0...",
    "name": "Device abc-123",
    "enabled": true,
    "status": "enabled",
    "limit_usd": 5.0,
    "used_usd": 0,
    "limit_reset": "monthly",
    "allowed_models": ["claude-haiku-4-5"],
    "ip_allowlist": [],
    "expires_at": null,
    "include_byok_in_limit": true,
    "rate_limit": { "rpm": 0, "tpm": 0 },
    "metadata": { "tenant_id": "acme", "device_id": "abc-123" },
    "created_via": "provisioning_api",
    "created_at": "2026-10-01T12:00:00Z"
  },
  "meta": { "request_id": "01a1..." }
}

Damit Sie das Erstellen gefahrlos wiederholen können, senden Sie einen Idempotency-Key-Header mit. Eine Wiederholung mit demselben Wert liefert die erste Antwort, allerdings ohne das Secret. Der Schlüssel liefert diese Antwort 24 Stunden lang, auch wenn die Ressource inzwischen gelöscht wurde; um sie neu anzulegen, verwenden Sie einen neuen Schlüssel.

Schlüssel auflisten und filtern

GET /api/v1/keys

Mit ?metadata.<name>=<value> filtern Sie nach einem beliebigen Metadatenfeld. Die Ergebnisse kommen seitenweise: Für die nächste Seite übergeben Sie meta.next_cursor als cursor.

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

# only keys tagged tenant_id=acme, 50 at a time
curl "https://synthorai.io/api/v1/keys?metadata.tenant_id=acme&limit=50" \
  -H "Authorization: Bearer sk-syn-admin-..."

Lesen, ändern, rotieren und löschen

• GET /api/v1/keys/{id} gibt einen einzelnen Schlüssel zurück.
• PATCH /api/v1/keys/{id} ändert nur die Felder, die Sie senden. "enabled": false sperrt den Schlüssel, ohne ihn zu löschen.
• POST /api/v1/keys/{id}/rotate gibt dem Schlüssel ein neues Secret. Das alte funktioniert sofort nicht mehr.
• DELETE /api/v1/keys/{id} löscht den Schlüssel. Anfragen mit ihm erhalten sofort 401.

# stop a key without deleting it
curl -X PATCH https://synthorai.io/api/v1/keys/42 \
  -H "Authorization: Bearer sk-syn-admin-..." \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

# give it a new secret
curl -X POST https://synthorai.io/api/v1/keys/42/rotate \
  -H "Authorization: Bearer sk-syn-admin-..."

# delete it
curl -X DELETE https://synthorai.io/api/v1/keys/42 \
  -H "Authorization: Bearer sk-syn-admin-..."

Ein Admin-Schlüssel handelt für genau ein Mitglied: die Person, die ihn erstellt hat, oder den Eigentümer, wenn der Schlüssel dem Workspace gehört und diese Person gegangen ist. Er kann nur die Schlüssel dieses Mitglieds ändern, rotieren und löschen, auch die, die er selbst erstellt hat. Beim Schlüssel eines anderen Mitglieds lautet die Antwort 403 not_key_creator, selbst mit dem Admin-Schlüssel des Eigentümers. Auf einer dedizierten Instanz kann jeder Admin-Schlüssel des Workspace die Schlüssel aller Mitglieder verwalten, so wie Admins in der Konsole. Hat ein Admin einen Schlüssel gesperrt, kann nur ein Admin ihn wieder aktivieren; alle anderen erhalten 403 disabled_by_admin.

Limits und Ausgaben

limit_usd gibt an, wie viel der Schlüssel ausgeben darf, used_usd, wie viel er ausgegeben hat. Ist das Limit erreicht, wechselt status auf limit_reached, und Anfragen werden abgelehnt, bis Sie das Limit anheben oder der Zeitraum neu beginnt.

Sie planen Ausgabenlimits pro Schlüssel? Der LLM-API-Kostenrechner rechnet das erwartete Token-Volumen eines Kunden in einen Monatsbetrag um, den Sie als limit_usd setzen können.

Fehler

Fehler kommen im Format der Management-API: error.code nennt den Grund, error.message sagt, was zu tun ist. Unter /api/provisioning/keys steht derselbe Code in error.type. Diese Codes betreffen speziell Admin-Schlüssel und die Schlüssel-Endpunkte:

Provisioning-Schlüssel und /api/provisioning

Schlüssel, die vor der Einführung der Admin-Schlüssel ausgestellt wurden (sk-syn-prov-), funktionieren weiter und haben die Scopes keys.read und keys.write. Die frühere Adresse /api/provisioning/keys bleibt mit ihren eigenen Feldnamen (quota, status) erreichbar. Für neue Integrationen nehmen Sie /api/v1/keys.

Die Management-API deckt außerdem die Abrechnung, das Anfrageprotokoll, Prompts und die Workspace-Einstellungen ab. Mehr dazu in der API-Übersicht und im OpenAPI-Dokument.