Schnittstelle (REST-API)
Adresse: /einstellungen/api · Recht: REST-API & Zugangsschlüssel verwalten
(api.manage)
Die Schnittstelle unter /api/v1 erlaubt eigenen Werkzeugen den Zugriff – der
Vereinswebsite, einem Anmeldetool, einer eigenen Auswertung.
Zugang beantragen
Die Schnittstelle ist nicht von Haus aus offen. Sie wird beantragt – mit Verwendungszweck – und von der Instanz-Verwaltung freigeschaltet.
Bereiche freigeben
Je Bereich (Material, Mitglieder, Veranstaltungen, Finanzen …) wird eingestellt:
| Stufe | Bedeutung |
|---|---|
| aus | Kein Zugriff |
| nur lesen | Lesender Zugriff |
| lesen & bearbeiten | Voller Zugriff |
Diese Einstellung ist die Obergrenze für alle Schlüssel. Ein Schlüssel kann nie mehr dürfen als der Bereich hergibt – auch wenn er weiter gefasst ausgestellt wurde.
Zugangsschlüssel
Ein Zugangsschlüssel ist das Passwort eines Programms.
- Laufzeit: 30, 90 oder 180 Tage – höchstens sechs Monate
- Der Schlüssel wird genau einmal angezeigt. Danach nie wieder.
- Je Schlüssel lässt sich die Zahl der Anfragen pro Minute begrenzen
- Letzte Nutzung und Aufrufzahl sind einsehbar
- Widerrufen macht ihn sofort ungültig
:::caution Beim Erzeugen sofort sichern Der Schlüssel erscheint ein einziges Mal. Leg ihn direkt dort ab, wo er hingehört – in die Konfiguration deines Werkzeugs oder in einen Passwortspeicher. Verloren heißt: neu erzeugen.
Und: Ein Schlüssel gehört niemals in Frontend-Code einer Website. Wer die Seite aufruft, kann ihn auslesen. :::
Ablauf-Erinnerung
14 Tage und 3 Tage vor Ablauf eines Schlüssels geht automatisch eine Mail heraus. Das verhindert die Website, die an einem Dienstagmorgen ohne Vorwarnung keine Termine mehr anzeigt.
Nachvollziehbarkeit
Jeder schreibende Zugriff steht im Aktivitätsprotokoll unter dem Schlüsselnamen.
Deshalb lohnen sprechende Namen: Website Termine, Anmeldetool, Auswertung Kasse – nicht Test oder Key 2.
Technische Beschreibung
Eine maschinenlesbare Beschreibung für Postman, Insomnia oder Client-Generatoren liegt
unter /api/v1/openapi.json.
Die ausführliche Entwicklerdokumentation ist nicht Teil dieses Handbuchs; sie liegt im
Anwendungs-Repository unter docs/REST-API.md.
Wann sich das lohnt – und wann nicht
Lohnt sich: Termine automatisch auf der Vereinswebsite anzeigen, eine wiederkehrende Auswertung, die Anbindung eines bestehenden Werkzeugs.
Lohnt sich nicht: Ein einmaliger Datenabzug – dafür gibt es in fast jedem Bereich einen Export als CSV, Excel oder PDF, ohne Antrag und ohne Schlüsselverwaltung.