Authentifizierung und API-Schlüssel

Jede Abfrage eines Datensatzes trägt den Schlüssel im Header Authorization nach dem Schema Bearer. Ein Schlüssel besteht aus dem Präfix qk_live_ und 40 weiteren Zeichen. Die API nimmt ihn nur im Header an, nicht als Parameter in der Adresse. So landet er nicht in Server-Logs oder im Browserverlauf.

curl "https://api.quellenkontor.dev/v1/hr/mindestlohn" \
  -H "Authorization: Bearer $QK_KEY"

const res = await fetch("https://api.quellenkontor.dev/v1/hr/mindestlohn", {
  headers: { Authorization: `Bearer ${process.env.QK_KEY}` },
});

import os, requests

r = requests.get(
    "https://api.quellenkontor.dev/v1/hr/mindestlohn",
    headers={"Authorization": f"Bearer {os.environ['QK_KEY']}"},
    timeout=15,
)

SDK und CLI setzen den Header selbst. Sie lesen den Schlüssel aus QK_KEY, wenn du keinen übergibst.

Einige Adressen sind offen, damit du die API erkunden kannst, bevor du ein Konto hast. Sie zählen nicht gegen ein Kontingent.

Jede Abfrage eines Datensatzes braucht sonst einen Schlüssel, auch im Tarif Kostenlos. Eine Ausnahme ist die Sandbox: drei Datensätze antworten auch ganz ohne Konto, dafür streng begrenzt.

Sandbox: drei Datensätze ohne Konto

Mindestlohn, Feiertage, Beitragsbemessungsgrenzen beantworten eine Abfrage ohne den Header Authorization, begrenzt auf 50 Abfragen am Tag je IP-Adresse (rollierend, kein fester Kalendertag). Praktisch für einen ersten Test in der Konsole oder ein öffentliches Widget ohne eigenes Backend. Sobald du einen Header Authorization mitschickst, egal ob gültig, greift die Sandbox nicht mehr, dann zählt der normale Weg mit Schlüssel.

curl "https://api.quellenkontor.dev/v1/hr/mindestlohn?datum=2027-01-15"

Die Antwort ist inhaltlich dieselbe wie mit Schlüssel, trägt zusätzlich einen Hinweis im Feld hinweise und den Header X-Kostenloser-Schluessel. Für alle Datensätze und ein Kontingent im Monat statt am Tag lohnt sich der kostenlose Schlüssel, siehe Schnellstart.

• Der Schlüssel gehört auf den Server: in eine Umgebungsvariable, einen Secret-Speicher wie die Environment Variables bei Vercel oder die Secrets in GitHub Actions.
• Nie in Frontend-Code, mobile Apps oder öffentliche Repositories. Alles, was im Browser läuft, kann jeder Besucher auslesen.
• Dateien wie .env gehören in .gitignore.
• Bei uns liegt nur ein Hash des Schlüssels. Wir können dir einen verlorenen Schlüssel deshalb nicht erneut anzeigen, nur einen neuen erzeugen lassen.

Leg für jede Umgebung und jede Anwendung einen eigenen Schlüssel an, zum Beispiel "Produktion", "Staging" und "Entwicklung". Im Konto siehst du je Schlüssel, wann er zuletzt genutzt wurde. Das Kontingent gilt für das ganze Konto, nicht je Schlüssel.

Wenn ein Mitarbeiter geht oder du Schlüssel regelmäßig erneuerst, tauschst du sie in vier Schritten, ohne dass eine Abfrage scheitert:

1. Im Konto einen neuen Schlüssel erzeugen. Der alte bleibt aktiv.
2. Den neuen Schlüssel in deiner Konfiguration hinterlegen und die Anwendung neu ausrollen.
3. Im Konto prüfen, dass der alte Schlüssel nicht mehr genutzt wird: Die Spalte "Zuletzt genutzt" bleibt stehen.
4. Den alten Schlüssel sperren.

Ein gesperrter Schlüssel wirkt sofort nicht mehr: Die nächste Abfrage mit ihm bekommt den Status 401 und den Code schluessel_ungueltig. Eine Sperre lässt sich nicht aufheben. Erzeuge danach einen neuen Schlüssel.

Antworten mit Status 401 tragen zusätzlich den Header WWW-Authenticate. Der MCP-Server antwortet bei fehlendem Schlüssel ebenfalls mit 401, damit Clients den Bedarf erkennen. Alle weiteren Codes stehen unter Fehler.

Das Konto auf der Website nutzt keine Passwörter. Du meldest dich über einen Link per E-Mail an, der 20 Minuten gilt und nur einmal funktioniert. Danach bleibst du 30 Tage angemeldet. "Abmelden" beendet die Sitzung auf allen Geräten. Deine API-Schlüssel bleiben davon unberührt: Sie gelten, bis du sie sperrst.