Authentifizierung
Welcher Key was kann, wie er geschützt, begrenzt und ersetzt wird und was seine Fehler bedeuten.
Zwei Arten von Keys
Neue Keys beginnen mit sk-tl-v1-. Bestehende sk-eu--Keys bleiben gültig. Beide Key-Arten sind Geheimwerte und werden als Authorization: Bearer <key> über HTTPS gesendet.
| Inferenz-Key | Management-Key | |
|---|---|---|
| Zweck | Ruft Modelle auf. | Verwaltet die Inferenz-Keys der Organisation und liest ihr Guthaben. |
| Endpunkt | Das Gateway, /v1/... | Die Verwaltungs-API auf dem Dashboard-Host, /api/... |
| Angelegt unter | API-Keys, von Inhabern, Admins und Entwicklern. | Management-Keys, von Inhabern und Admins. |
| Gehört zu | Einem Workspace. | Der Organisation. |
| Scopes | keine | keys:read, keys:write, workspaces:read, credits:read |
| Variable | TOKENLANE_API_KEY | TOKENLANE_MANAGEMENT_KEY |
Keiner kann die Aufgabe des anderen übernehmen: Ein Management-Key ruft keine Modelle auf, ein Inferenz-Key verwaltet das Konto nicht. Die Anmeldung im Dashboard nutzt eine Browser-Sitzung, keinen Key.
Den Geheimwert schützen
Ein Key wird einmal angezeigt und nur als Hash gespeichert; ein verlorener Key wird ersetzt, nicht wiederhergestellt.
- Den Key aus der Umgebung oder der Geheimnisverwaltung des Servers lesen.
- Nie in Browser- oder Mobile-App-Code, URLs, Versionsverwaltung, Logs, Support-Nachrichten oder geteilte Notebooks schreiben.
- Pro Anwendung und Umgebung einen eigenen Key verwenden.
- Bei einem Leck den Key sofort sperren und einen neuen anlegen. Das Präfix
sk-tl-v1-hilft Secret-Scannern, veröffentlichte Keys zu finden.
Einen Key begrenzen
Regeln gehören zum Key: unter Erweitert setzen oder als policy über die Verwaltungs-API. Änderungen erreichen das Gateway innerhalb von Sekunden.
Das Gateway setzt außerdem geerbte Organisations- und Workspace-Regeln durch. Jede Ebene kann Modelle, Provider und Verarbeitungsanforderungen einschränken; ein Request darf die Schnittmenge nicht erweitern. Workspace-Budgets gelten gemeinsam für ihre Inferenz-Keys. Die Verwaltung zeigt wirksame Regeln samt Herkunft; siehe Organisationen und Workspaces.
| Regel | Wirkung | Fehler |
|---|---|---|
expires_at | Weist den Key ab diesem Zeitpunkt ab; laufende Anfragen und Streams werden beendet. | 401 authentication |
limit, limit_reset | Budget in EUR, wahlweise täglich, wöchentlich (ab Montag) oder monatlich in UTC zurückgesetzt. | 402 insufficient_credits, wenn der Rest eine Anfrage nicht deckt |
allowed_models | Modell-IDs oder Muster mit *. Fallbacks außerhalb der Liste werden übersprungen. | 403 permission_denied; remedy_hint nennt die erlaubten Modelle |
server_tools | web_search erlaubt das Plugin web. | 403 permission_denied |
capture | Speichert Prompts und Antworten dieses Keys zum späteren Abruf. | keiner |
Einen Key ersetzen
Es gibt keine Rotationsfunktion. Stattdessen:
- Den neuen Key im selben Workspace mit denselben Regeln anlegen.
- Ihn ausrollen und beim alten Key Zuletzt verwendet beobachten.
- Den alten Key sperren: Er wird binnen Sekunden abgewiesen und lässt sich wieder freigeben.
- Ihn löschen, sobald alles sicher ist; mit ihm erzeugte Generations behalten seine Key-ID.
Mit einem Management-Key automatisieren
Die Verwaltungs-API liegt auf dem Dashboard-Host, nicht auf dem Gateway. Diese Anfrage listet die Keys der Organisation auf: Namen, Präfixe, Policies und Nutzung, nie einen Geheimwert.
curl
curl --request GET \
--url 'https://tokenlane.de/api/keys' \
--header 'Authorization: Bearer YOUR_MANAGEMENT_KEY'
node
const response = await fetch("https://tokenlane.de/api/keys", {
method: "GET",
headers: {
"Authorization": "Bearer " + process.env.TOKENLANE_MANAGEMENT_KEY,
},
});
console.log(await response.text());
python
import os
import urllib.request
request = urllib.request.Request(
"https://tokenlane.de/api/keys",
method="GET",
headers={
"Authorization": "Bearer " + os.environ["TOKENLANE_MANAGEMENT_KEY"],
},
)
with urllib.request.urlopen(request) as response:
print(response.read().decode("utf-8"))
vercel
// This operation uses HTTP directly.
const response = await fetch("https://tokenlane.de/api/keys", {
method: "GET",
headers: {
"Authorization": "Bearer " + process.env.TOKENLANE_MANAGEMENT_KEY,
},
});
console.log(await response.text());
Ein Management-Key kann keine Workspaces anlegen, keine Mitglieder verwalten, keine Logs oder Aktivität lesen, keine Management-Keys anlegen oder ändern und keine Guthaben-Einstellungen wie Auto-Aufladung, Rechnungsdaten und Erstattungen ändern. Dafür ist eine Admin-Sitzung im Dashboard nötig. Solche Aufrufe liefern 403 FORBIDDEN; ein fehlender Scope steht in details. Jede Operation der API-Referenz nennt ihren Scope.
401 und 403 beheben
| Status | Gateway | Verwaltungs-API |
|---|---|---|
| 401 | authentication: Der Header fehlt, der Key ist abgelaufen oder ungültig. Ungültig umfasst Tippfehler sowie gelöschte, gesperrte und falsche Key-Arten gleichermaßen, damit Fehler nichts über vorhandene Keys verraten. | UNAUTHORIZED: fehlender, ungültiger oder abgelaufener Key oder ein Inferenz-Key. |
| 403 | permission_denied: Die Regeln des Keys schließen Modell oder Tool aus, oder die Organisation ist gesperrt. issues und remedy_hint lesen. | FORBIDDEN: Ein Scope fehlt; details nennt ihn. |
Vor einer Wiederholung den Key oder seine Regeln korrigieren; keiner der Status heilt von selbst. Formate: Fehlerkataloge von Gateway und Verwaltungs-API. Wiederholungsregeln: Fehler und Wiederholung.
Als Nächstes
- Schnellstart: die erste Anfrage
- Organisationen und Workspaces: wer Keys anlegt, wo das Guthaben liegt
- Von OpenRouter umsteigen