Berechtigungen und Firewall: wer darf was

Ein API-Schlüssel ist ein Zugang zu deinen Daten. Diese Seite erklärt, welche Schrauben du hast und wie du sie sinnvoll einstellst.

1. Die Berechtigungsstufe

Jeder Schlüssel bekommt dieselbe Art von Stufe wie ein Benutzer. Er kommt damit an genau die Daten, die diese Stufe auch in der Oberfläche sehen darf — keine Ausnahmen, keine Sonderregeln.

Stufe	Kommt zum Beispiel an
Administrator	alles, auch Einstellungen, Vorlagen und Mailkonten
Buchhaltung	Rechnungen, Zahlungen, Kassenbuch, Abos — dazu alles der Stufen darunter
Backoffice	Seiten, Blog, Forum, Newsletter, Nachrichten
Mitarbeiter	Kontakte, Tiere, Termine, Buchungen, Stammdaten

Faustregel: die niedrigste Stufe, die für die Aufgabe reicht. Ein Schlüssel für eine Terminübersicht braucht keine Rechnungsdaten.

Zwei Dinge gehen auch mit der höchsten Stufe nicht: Kennwörter und andere Zugangscodes sind über die Schnittstelle weder lesbar noch schreibbar. Und die Berechtigungsstufe eines Kontakts ändert nur ein Administrator-Schlüssel — ein Schlüssel der Stufe Backoffice kann also weder sich selbst noch andere höherstufen.

2. Nur lesen

Der Schalter Schreiben erlauben ist die wirksamste einzelne Maßnahme. Ist er aus, werden alle Aufrufe abgewiesen, die etwas ändern würden — unabhängig von der Stufe.

Für Auswertungen, Anzeigetafeln, Datenexporte und alles, was nur schauen soll: immer ausschalten.

3. Nur bestimmte Bereiche

Im Feld Nur diese Bereiche schränkst du den Schlüssel weiter ein. Leer heißt: alle Bereiche, die die Stufe erlaubt. Sonst trägst du die Bereichsnamen mit Komma getrennt ein:

contacts, pets, invoices

Ein Stern steht für beliebige Zeichen — so erfasst du eine ganze Familie:

pension*

Das trifft pensionbookings, pensionplaces, pensionrequests und alle weiteren Bereiche, die mit „pension“ beginnen.

Die Bereichsnamen findest du unter /api/v1/.

4. Im Namen eines Mitarbeiters arbeiten

Freiwillig kannst du dem Schlüssel einen Kontakt zuordnen. Zwei Dinge ändern sich dann:

• Änderungen erscheinen im Protokoll unter diesem Namen — du siehst also, in wessen Namen die Schnittstelle gearbeitet hat.
• Die Rechte des Kontakts begrenzen den Schlüssel zusätzlich. Ist der Kontakt nur Mitarbeiter, kommt der Schlüssel auch dann nicht an Rechnungen, wenn seine Stufe „Administrator“ lautet.

Ohne Kontakt arbeitet der Schlüssel als technischer Zugang; Protokolleinträge tragen dann seine Bezeichnung.

5. Die IP-Freigabeliste

Läuft das aufrufende Programm auf einem festen Server, trage dessen Adresse ein. Der Schlüssel ist dann überall sonst wertlos — selbst wenn er in falsche Hände gerät.

Eine Adresse je Zeile. Erlaubt sind einzelne Adressen, ganze Bereiche und Präfixe mit Stern:

203.0.113.7        # Server der Buchhaltung
192.168.1.0/24     # Büro
2001:db8::/32      # Rechenzentrum
10.0.0.*           # VPN

Text nach einem # ist ein Kommentar. Leere Liste bedeutet: alle Absender sind erlaubt.

Welche Adresse hat mein Server? Ruf /api/v1/me von dort auf. Unter firewall.your_ip steht, mit welcher Adresse PetWorkers ihn sieht — genau die gehört in die Liste.

6. Das Tempo

Jeder Schlüssel hat ein Kontingent an Anfragen je Minute. Vorgabe sind 120. Das bremst zwei Dinge: überlastende Zugriffe und Programme, die sich in einer Schleife verheddert haben.

Jede Antwort sagt dir, wie es um dein Kontingent steht:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1755463200

Ist es aufgebraucht, kommt Status 429 mit der Kopfzeile Retry-After: So viele Sekunden soll dein Programm warten. Alle mitgelieferten Beispielskripte tun das von selbst.

Der Wert 0 schaltet die Bremse ab. Das ist für einen einmaligen Massenabgleich sinnvoll, sollte danach aber wieder zurückgestellt werden.

7. Was von allein passiert

Drei Dinge laufen ohne dein Zutun:

• Nur über HTTPS. Aufrufe über unverschlüsseltes HTTP werden abgewiesen. Ein Schlüssel, der im Klartext übers Netz geht, ist keiner mehr.
• Absender-Sperre. Nach 20 fehlgeschlagenen Anmeldungen innerhalb einer Viertelstunde (unbekannter, abgelaufener oder von dieser Adresse nicht zugelassener Schlüssel) wird die Adresse für 15 Minuten gesperrt. Das macht das Durchprobieren von Schlüsseln aussichtslos. Ein gültiger Schlüssel, der an einer Berechtigung scheitert, zählt dabei nicht mit — ein falsch eingestelltes Programm sperrt dir nicht den Anschluss.
• Keine Verwaltung der eigenen Schlüssel. Die Schnittstelle kann die API-Schlüssel selbst nicht lesen und nicht ändern — sonst könnte sich ein Schlüssel selbst höherstufen oder seine Sperren löschen. Schlüssel gibt es nur in der Oberfläche.

8. Der Notaus

Unter System → Einstellungen gibt es den Eintrag api.enabled. Schaltest du ihn aus, ist die gesamte Schnittstelle geschlossen; jeder Aufruf bekommt „503 – nicht verfügbar“.

Das ist der Hebel für den Notfall — etwa wenn ein angebundenes System Amok läuft und du erst in Ruhe schauen willst.

9. Wer hat was gemacht

Unter System → API-Schlüssel → Zugriffsprotokoll siehst du die Aufrufe: Zeitpunkt, Schlüssel, Methode, Pfad, Ergebnis, Dauer und Absender-Adresse.

Wie viel mitgeschrieben wird, stellst du je Schlüssel ein:

Nichts	gar kein Protokoll
Fehler und Änderungen	Vorgabe — das Nützlichste bei geringstem Umfang
Jeden Aufruf	für die Fehlersuche, erzeugt viele Einträge

Fehlgeschlagene Anmeldungen werden immer festgehalten, unabhängig von dieser Einstellung. Die Inhalte der Anfragen werden nie gespeichert — sie enthalten Kunden- und Gesundheitsdaten, und ein Protokoll davon wäre eine zweite, ungeschützte Kopie.

Einträge werden 30 Tage aufbewahrt und danach automatisch entfernt.

10. Wenn ein Schlüssel weg ist

Ist ein Schlüssel in falsche Hände geraten, hast du zwei Möglichkeiten in der Liste:

• Neu vergeben — der Schlüssel behält alle Einstellungen, bekommt aber einen neuen Wert. Der alte ist sofort ungültig. Die angebundenen Programme brauchen den neuen Wert.
• Löschen — der Zugang ist weg. Zugriffe damit werden ab sofort abgewiesen.