Die API

Die API wird von demselben Cloudflare Worker bedient, der deine Links auflöst, auf dem Kilo-QR-Origin. Heute heißt das, Anfragen gehen an qr2r.com unter dem /api-Präfix:

https://qr2r.com/api

Jeder Pfad in diesen Anleitungen ist relativ zu dieser Basis - /links bedeutet https://qr2r.com/api/links. Ein schneller Weg, zu bestätigen, dass ein Schlüssel funktioniert, ist die API-Wurzel, die deine Identität zurückspiegelt:

{ "api": "qr2r", "version": 0, "user": { "uid": 42, "email": "", "admin": false } }

Sende deinen Schlüssel als Bearer-Token im Authorization-Header. Der Schlüssel wird vor dem Sitzungscookie geprüft, sodass ein API-Client in einem Auth-Modus bleibt, ohne dass ein veraltetes Browser-Cookie hereinsickert.

Authorization: Bearer qr2r_live_1a2b3c…

Schlüssel beginnen mit qr2r_live_ (oder qr2r_test_ für einen Dev-Modus-Schlüssel). Dieses qr2r_-Präfix ist ein Infrastruktur-Bezeichner, der bewusst nicht umbenannt wurde - derselbe Grund, aus dem die Domain noch qr2r.com ist. Du erzeugst einen Schlüssel im Dashboard unter API keys; der volle Token wird bei der Erstellung einmal angezeigt, und Kilo speichert nur seinen SHA-256-Hash, also leg ihn direkt in einen Secret-Manager. Eine Anfrage ohne gültigen Schlüssel (und ohne Sitzung) wird abgelehnt:

{ "error": "unauthorized" }

Ein Schlüssel trägt einen oder beide von zwei Scopes. Ein Lese-Schlüssel darf nur sichere Methoden aufrufen - GET, HEAD, OPTIONS. Ein Schreib-Schlüssel darf zusätzlich POST, PUT, PATCH und DELETE. Ein Schreibversuch mit einem reinen Lese-Schlüssel wird abgelehnt:

{ "error": "insufficient_scope", "required": "write" }

Scopes sind die ganze Berechtigungsgeschichte eines Schlüssels: Ein Schlüssel kann Links, Regeln verwalten und Analysen lesen, aber er kann nie Mitglieder, Abrechnung oder andere Schlüssel verwalten - diese Aktionen bleiben an eine interaktive Sitzung gebunden. Gib einer Integration einen Lese-Schlüssel, wenn sie nur Zahlen abruft.

Jede Fehlerantwort ist ein JSON-Objekt mit einem error-String, plus Zusatzfeldern, wo sie helfen. Validierungsfehler tragen die vollständige Problemliste unter issues:

{ "error": "invalid_body", "issues": [ /* zod issues */ ] }

Die Codes, denen du am häufigsten begegnest:

• 400 invalid_body - der Anfragekörper hat die Validierung nicht bestanden.
• 401 unauthorized - fehlender oder ungültiger Schlüssel.
• 402 plan_required - die Funktion braucht einen höheren Tarif (trägt feature).
• 403 insufficient_scope / forbidden - der Schlüssel kann diese Methode oder Aktion nicht ausführen.
• 404 not_found - kein solcher Link, keine solche Regel oder Domain in deinem Arbeitsbereich.
• 409 - ein Konflikt, etwa name_taken oder cap_reached.
• 422 destination_unsafe - das Ziel hat die Sicherheitsprüfung nicht bestanden.
• 429 rate_limited - zu viele Anfragen (siehe unten).

Authentifizierte Anfragen werden ratenbegrenzt. Der allgemeine Bucket erlaubt 60 Anfragen pro Minute pro Nutzer. Zusätzlich bekommt ein API-Schlüssel seine eigene Obergrenze pro Schlüssel und pro Minute, genommen aus dem api_rpm-Limit deines Tarifs. Überschreite eines, und die Antwort ist:

{ "error": "rate_limited", "retry_after": 42 }

Der retry_after-Wert (auch als Retry-After-Header gesendet) ist die Zahl der Sekunden, bis sich das Fenster zurücksetzt. Warte so lange und versuche es erneut.

Mit einem Schlüssel in der Hand führt die nächste Anleitung durch die Link-Endpoints, einen Aufruf nach dem anderen.