# API-Keys

> Persönliche Zugriffstokens erstellen, verwalten und widerrufen und die OpenAI-kompatible Chat-Completions-API für Skripte und eigenen Code nutzen.

![Der Tab Token in den Einstellungen mit dem Formular Neues Token erstellen und der Liste Deine Token](https://docs.platte.ai/screenshots/api-tokens.webp)

Ein **persönlicher Zugriffstoken** ist Plattes API-Key: Er öffnet die Chat-Completions-API für alles, was nicht die Oberfläche ist — Skripte, eigene Programme und Werkzeuge wie OpenCode. Andere Werkzeuge nennen so etwas API-Key. Du erstellst den Token in den Einstellungen, übergibst ihn als Bearer-Token und rufst damit dieselben Modelle auf, die auch im Chat antworten. Jede Anfrage läuft auf deinen Namen und zählt auf dein Limit. Wie du OpenCode mit einem Token verbindest, steht auf [OpenCode-Integration](./opencode).

## Einen Zugriffstoken erstellen

Öffne unten in der Seitenleiste dein Namensmenü und wähle **Einstellungen**, dann den Tab **Token**. Der Hinweis oben erklärt, wofür der Token gilt: Skripte und Tools rufen damit den OpenAI-kompatiblen Endpunkt `/api/v1/chat/completions` in deinem Namen auf.

1. Trage im oberen Feld einen Namen ein — der Platzhalter lautet **Name (z. B. mein-script)**. Das Feld ist optional; ohne Namen erscheint der Token später als **(ohne Namen)**.
2. Trage im Feld daneben die Gültigkeit ein — **Ablauf (Tage, leer = nie)**. Bleibt das Feld leer, läuft der Token nie ab. Die Obergrenze liegt bei einem Jahr: größere Werte kürzt Platte auf 365 Tage, und mindestens ein Tag ist Pflicht.
3. Wähle **Erstellen**.

Das rohe Token erscheint danach genau einmal, in einem grünen Banner mit dem Hinweis **Token erstellt — kopiere es jetzt**. Über **Kopieren** landet es in der Zwischenablage; über das Schließen-Symbol verschwindet das Banner. Platte speichert nur einen Hash des Tokens — kannst du ihn später nicht mehr sehen, bleibt nur der Weg über einen neuen Token. Der Wert beginnt mit `platte_pat_`.

## Token verwalten und widerrufen

Unter **Deine Token** listet Platte alle Tokens — aktive, abgelaufene und widerrufene — neueste zuerst; daneben steht die Zahl der aktiven, etwa **2 aktiv**. Jede Zeile zeigt den Namen, ein Badge **Aktiv**, **Abgelaufen** oder **Widerrufen**, dazu das Erstellungsdatum, **Zuletzt verwendet** mit Datum oder **nie** und **Läuft ab** mit Datum oder **nie**. Ist die Liste leer, steht dort **Noch keine Token**.

Über **Widerrufen** entfernst du einen Token. Platte fragt vorher nach und stellt klar: „Dieses Token widerrufen? Skripte, die es verwenden, funktionieren sofort nicht mehr.“ Danach bleibt die Zeile mit dem Badge **Widerrufen** sichtbar, abgeblendet und ohne weiteren Knopf — die Historie verschwindet nicht. Mit **Aktualisieren** holst du die Liste neu, etwa damit **Zuletzt verwendet** nach der ersten Anfrage erscheint.

## Die API aufrufen

Die Basis-URL folgt deiner Instanz: `https://<name>.on.platte.ai/api/v1`. Der Endpunkt für Antworten ist `POST /api/v1/chat/completions` und spricht das Format der OpenAI-Chat-Completions. Den Token sendest du als Bearer im Kopf `Authorization`:

```
curl https://<name>.on.platte.ai/api/v1/chat/completions \
  -H "Authorization: Bearer platte_pat_…" \
  -H "Content-Type: application/json" \
  -d '{"model": "<modell-id>", "messages": [{"role": "user", "content": "Hallo!"}]}'
```

Antwort und Fehlercodes kommen unverändert von der Schnittstelle dahinter, damit sich OpenAI-kompatible Client-Bibliotheken ohne Anpassung dagegen betreiben lassen. Optional kannst du mit dem Kopf `X-Client-Suffix` einen eigenen Namen mitgeben, damit dein Verkehr in der Nutzungsauswertung unterscheidbar ist — erlaubt sind Buchstaben, Ziffern, `_` und `-`, höchstens 64 Zeichen. Er erscheint dort als `platte-pat:<suffix>`.

## Antworten streamen

Setze `stream: true` in den Anfragekörper, um Token einzeln zu empfangen, statt auf die ganze Antwort zu warten. Platte liefert dann einen Server-Sent-Events-Stream vom Typ `text/event-stream`. Auch der Rate-Limit-Hinweis des Anbieters wird durchgereicht, sodass Clients bei einer 429-Antwort automatisch warten.

## Modelle und Fehler

Nicht jedes Modell ist über einen Token erreichbar. Ein Administrator gibt pro Modell frei, ob es für persönliche Zugriffstokens offen ist; `GET /api/v1/models` listet nur die freigegebenen. Die wichtigsten Antworten:

- **401** — der Token fehlt, ist abgelaufen oder widerrufen. Erwartet wird `Authorization: Bearer <pat>`.
- **403** — das angefragte Modell ist nicht über persönliche Zugriffstokens verfügbar.
- **502** — die Schnittstelle dahinter war nicht erreichbar; ein neuer Versuch ist sinnvoll.

In einer Demo-Instanz führt der Eintrag **Token** zu einem Gesprächsangebot statt zur Token-Verwaltung; die Karte **Benutzerdefinierte Integration** weiter unten verhält sich genauso.

## Die API aus eigenem Code aufrufen

Die Karte **Benutzerdefinierte Integration** richtet sich an eigenen Code. Oben zeigt der Dialog die Tabelle **Über die API verfügbare Modelle** mit Anzeigename und ID — dieselbe Auswahl, die auch der Token erreicht. Darunter stehen drei Beispiele, die sich nur im Aufruf unterscheiden: **Fetch**, **TypeScript (openai)** und **Python (openai)**. Jedes Beispiel führt in drei Schritten durch dasselbe Muster: Zugriffstoken erstellen, die API aufrufen, Antworten streamen.

Für TypeScript sieht der Aufruf so aus — das `openai`-Paket funktioniert unverändert, weil nur Basis-URL und Schlüssel getauscht werden:

```
import OpenAI from "openai";


const client = new OpenAI({
  apiKey: "<dein-zugriffstoken>", // dein Platte-Zugriffstoken
  baseURL: "https://<name>.on.platte.ai/api/v1",
});


const res = await client.chat.completions.create({
  model: "<modell-id>",
  messages: [{ role: "user", content: "Hallo!" }],
});


console.log(res.choices[0].message.content);
```

Den Token erstellst du wie oben beschrieben; die Beispiele im Dialog tragen ihn nicht selbst ein, sondern lassen ihn als Platzhalter stehen.

## Zugriffstoken sicher verwahren

Ein Zugriffstoken ist ein Schlüssel zu deinem Konto: Wer ihn hat, ruft in deinem Namen Modelle auf — und verbraucht dabei deine Credits. Für den Umgang damit gelten ein paar einfache Regeln.

### Den Token nie im Code ablegen

Hart in den Quelltext geschrieben, steht er in jedem Commit, jeder Kopie und jedem geteilten Auszug. Lies ihn stattdessen aus einer Umgebungsvariable:

```
export PLATTE_API_TOKEN=platte_pat_…
```

Aus Python heraus:

```
import os
from openai import OpenAI


client = OpenAI(
    api_key=os.environ["PLATTE_API_TOKEN"],
    base_url="https://<name>.on.platte.ai/api/v1",
)
```

Nimm Dateien mit Zugangsdaten in `.gitignore` auf, damit sie nie in der Versionsverwaltung landen:

```
.env
.env.local
credentials.json
```

### Nie an den Browser ausliefern

Sobald ein Token in einer ausgelieferten Seite oder App steckt, ist er kein Geheimnis mehr: Er steht in den Entwicklerwerkzeugen, im Netzwerkverkehr und im Quelltext. Setze ihn ausschließlich auf deinem Server ein und lass den Server die Anfragen im Namen deiner Nutzer stellen.

### Ein Token pro Einsatzzweck

Teile einen Token nie zwischen Personen, Anwendungen oder Umgebungen. Jede Anfrage läuft auf den Nutzer, dem der Token gehört, und verbraucht dessen Credits — ein weitergegebener Token verschleiert also, wer was verursacht. Lege lieber für jeden Zweck einen eigenen an: Entwicklung und Produktion getrennt, jede Anwendung mit ihrem eigenen Token. Das begrenzt den Schaden eines Lecks, trennt die Nutzung in der Auswertung und macht das Erneuern einfach.

### Erneuern und widerrufen

Ein Token ohne Ablauf gilt, bis du ihn widerrufst. Vergib deshalb beim Anlegen eine Gültigkeit — **Ablauf (Tage, leer = nie)** — und erneuere den Token regelmäßig. Platte hat keinen eigenen Knopf zum Erneuern: Lege einen neuen Token an, stelle alle Werkzeuge darauf um und widerrufe danach den alten.

## Häufige Fragen

Welche Modelle erreicht mein Token?

Nur die, die ein Administrator für persönliche Zugriffstokens freigegeben hat. `GET /api/v1/models` und die Tabelle **Über die API verfügbare Modelle** zeigen genau diese Auswahl; ein anderes Modell beantwortet Platte mit dem Status 403.

Kann ich ein Token später noch einmal ansehen?

Nein. Platte speichert nur den Hash, das rohe Token zeigt sich einmal beim Erstellen. Ist es verloren, erstellst du einen neuen Token und widerrufst den alten, damit er nicht weiter gültig bleibt.

Zählt die Nutzung über die API auf mein Limit?

Ja. Jede Anfrage wird dem Nutzer zugeordnet, dem der Token gehört, und verbraucht dessen Credits — genau wie eine Anfrage aus dem Chat. Der optionale Kopf `X-Client-Suffix` hilft nur dabei, die verschiedenen Quellen auseinanderzuhalten.

Was tun, wenn ein Token abhandengekommen ist?

Widerrufe ihn sofort über **Widerrufen** in **Deine Token** — alles, was ihn benutzt, funktioniert augenblicklich nicht mehr. Lege danach einen neuen Token an und stelle deine Werkzeuge darauf um. Prüfe in der Nutzung und bei **Zuletzt verwendet**, ob vor dem Widerruf fremde Anfragen zu sehen waren.

Warum funktioniert mein Skript plötzlich nicht mehr?

Prüfe in **Deine Token** das Badge der betroffenen Zeile: **Widerrufen** heißt, der Zugang wurde entzogen, **Abgelaufen** heißt, die eingestellte Gültigkeit ist vorbei. In beiden Fällen hilft nur ein neuer Token. Steht dort **Aktiv**, liegt die Ursache meist im angefragten Modell — dann lohnt ein Blick, ob es noch für Tokens freigegeben ist.

**Nächster Schritt** → [OpenCode-Integration](./opencode)