Berechtigungen und Firewall: wer darf was

Mit einem API-Schlüssel erlaubst du einem Programm den Zugriff auf PetWorkers. Hier begrenzt du seine Rechte, Laufzeit und erlaubten Absender.

Begriffe: API bedeutet Schnittstelle für andere Programme. Ein Endpunkt ist eine bestimmte Abrufadresse. JSON ist das Textformat der Antworten; eine Kennung (id) bezeichnet einen Eintrag.

So begrenzt du einen vorhandenen Zugang

1. Öffne System → API-Schlüssel.
2. Klicke beim betreffenden Schlüssel auf das Stiftsymbol Bearbeiten.
3. Wähle die benötigte Berechtigungsstufe.
4. Trage unter Nur diese Bereiche die benötigten Bereiche ein.
5. Klicke auf Speichern.

Nach dem Speichern erscheint API-Schlüssel geändert.

1. So wählst du 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
BackOffice (Büro & Buchhaltung)	Rechnungen, Zahlungen, Kassenbuch, Abos — dazu alles der Stufen darunter
BackOffice (Sach- und Rechnungsbearbeitung)	Seiten, Blog, Forum, Newsletter, Nachrichten
Beratung, Training & Betreuung	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:

Was macht das? Diese Bereichsliste erlaubt nur die drei genannten Bereiche.

contacts, pets, invoices

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

Was macht das? Diese Bereichsfreigabe erlaubt alle Bereichsnamen, die mit pension beginnen.

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:

Was macht das? Diese Beispiele zeigen einzelne IP-Adressen und erlaubte Adressbereiche. Ersetze sie durch die tatsächlichen Absender.

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, bevor du die IP-Freigabeliste einschränkst. Unter firewall.your_ip steht, mit welcher Adresse PetWorkers ihn sieht — genau die gehört in die Liste. Bei einer bestehenden Sperre nennt error.message die erkannte Adresse.

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.

Erfolgreiche Antworten zeigen über diese Kopfzeilen das Kontingent. Fehlerantworten können ohne diese Angaben antworten:

Was macht das? Diese Antwort-Kopfzeilen zeigen das Anfragelimit und die verbleibenden Aufrufe.

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. Prüfe, ob dein verwendetes Skript diese Wartezeit berücksichtigt. Kurze Beispiele zeigen keinen vollständigen Wiederholungsablauf.

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	keine erfolgreichen Aufrufe; Fehler werden weiterhin protokolliert
Fehler und Änderungen	Vorgabe — das Nützlichste bei geringstem Umfang
Jeden Aufruf	für die Fehlersuche, erzeugt viele Einträge

Fehlgeschlagene Anmeldungen und Fehlerantworten werden unabhängig von dieser Einstellung protokolliert. Im Archivmodus entsteht kein Protokolleintrag. Gespeichert werden unter anderem Pfad, URL-Parameter und Fehlermeldung. Der JSON-Anfrageinhalt und die zurückgegebenen Fachdaten werden nicht mitgeschrieben.

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.