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-KeyManagement-Key
ZweckRuft Modelle auf.Verwaltet die Inferenz-Keys der Organisation und liest ihr Guthaben.
EndpunktDas Gateway, /v1/...Die Verwaltungs-API auf dem Dashboard-Host, /api/...
Angelegt unterAPI-Keys, von Inhabern, Admins und Entwicklern.Management-Keys, von Inhabern und Admins.
Gehört zuEinem Workspace.Der Organisation.
Scopeskeinekeys:read, keys:write, workspaces:read, credits:read
VariableTOKENLANE_API_KEYTOKENLANE_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.

RegelWirkungFehler
expires_atWeist den Key ab diesem Zeitpunkt ab; laufende Anfragen und Streams werden beendet.401 authentication
limit, limit_resetBudget 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_modelsModell-IDs oder Muster mit *. Fallbacks außerhalb der Liste werden übersprungen.403 permission_denied; remedy_hint nennt die erlaubten Modelle
server_toolsweb_search erlaubt das Plugin web.403 permission_denied
captureSpeichert Prompts und Antworten dieses Keys zum späteren Abruf.keiner

Einen Key ersetzen

Es gibt keine Rotationsfunktion. Stattdessen:

  1. Den neuen Key im selben Workspace mit denselben Regeln anlegen.
  2. Ihn ausrollen und beim alten Key Zuletzt verwendet beobachten.
  3. Den alten Key sperren: Er wird binnen Sekunden abgewiesen und lässt sich wieder freigeben.
  4. 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

StatusGatewayVerwaltungs-API
401authentication: 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.
403permission_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