# 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](https://tokenlane.de/keys), von Inhabern, Admins und Entwicklern. | [Management-Keys](https://tokenlane.de/settings/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](https://tokenlane.de/docs/guides/organizations-and-workspaces.md?lang=de).

| 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:

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
curl --request GET \
  --url 'https://tokenlane.de/api/keys' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_KEY'
```

### node

```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

```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

```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](https://tokenlane.de/docs/gateway/errors.md?lang=de) und [Verwaltungs-API](https://tokenlane.de/docs/management/errors.md?lang=de). Wiederholungsregeln: [Fehler und Wiederholung](https://tokenlane.de/docs/guides/errors-and-retries.md?lang=de).

## Als Nächstes

- [Schnellstart](https://tokenlane.de/docs/guides/quickstart.md?lang=de): die erste Anfrage
- [Organisationen und Workspaces](https://tokenlane.de/docs/guides/organizations-and-workspaces.md?lang=de): wer Keys anlegt, wo das Guthaben liegt
- [Von OpenRouter umsteigen](https://tokenlane.de/docs/guides/openrouter-migration.md?lang=de)