Bereiche (Scopes)

Was ein Aufruf darf, entscheiden drei Ebenen gemeinsam:

Ebene	Wo eingestellt	Wirkung
1. Obergrenze des Vereins	Einstellungen → API → Bereiche	Was die Schnittstelle für diese Instanz insgesamt hergibt: aus / nur lesen / lesen & bearbeiten
2. Bereiche des Schlüssels	beim Anlegen des Schlüssels	Was dieser eine Schlüssel darf
3. Der Endpunkt selbst	fest in der Anwendung	Welcher Bereich für diesen Aufruf nötig ist

Wirksam ist die Schnittmenge aus 1 und 2.

Token:      material:write, bank:write, mails:write
Obergrenze: material = lesen & bearbeiten
            bank     = nur lesen
            mails    = aus
─────────────────────────────────────────────────────
Wirksam:    material:write, bank:read

Das ist der Kern des Modells

Stellt ein Administrator einen Bereich auf nur lesen zurück, verlieren bestehende Schlüssel ihre Schreibrechte darin sofort – ohne dass jemand Schlüssel nachpflegen müsste. Genau dafür gibt es die Obergrenze.

Ein Bereich hat die Form <bereich>:read oder <bereich>:write. :write schließt :read desselben Bereichs ein – ein Werkzeug, das schreiben darf, muss nicht zusätzlich um Leserechte bitten.

Ab Werk steht jeder Bereich auf aus. Das gilt auch für Bereiche, die in einer späteren Version dazukommen: ein neuer Bereich öffnet sich nie von selbst.

Alle Bereiche

Die Spalte Interne Rechte zeigt, welche Rechte der Anwendung ein Schlüssel in diesem Bereich erhält. Ein Zugangsschlüssel ist kein Benutzerkonto, aber er soll auch keine zweite, konkurrierende Rechteverwaltung sein – deshalb bildet jeder Bereich fest auf die Einzelrechte ab, und alle vorhandenen Prüfungen greifen unverändert weiter.

Bereich	Inhalt	Interne Rechte (lesen / schreiben)
mitglieder	Stammdaten, Gruppenzugehörigkeit, Familien-Verknüpfungen, Gruppen-Historie, Kündigung	– / contacts.manage
gruppen	Stufen/Gruppen und Mail-Verteiler	– / contacts.manage
material	Exemplare, Artikel, Sets, Kategorien, Lagerorte	– / materials.write
fahrzeuge	Fahrzeugstammdaten	– / vehicles.write
packlisten	Merk-/Packlisten samt Positionen und Fahrzeugen	– / packing.write
verleih	Ausleihen, Verfügbarkeiten, Statuswechsel	verleih.read / verleih.manage
veranstaltungen	Lager und Aktionen samt Teilnehmenden, Zahlungen und Vorlagen	events.read / events.manage, events.participants
nachweise	Führungszeugnisse und befristete Nachweise – ohne die Dateien	nachweise.read / nachweise.manage
bank	Konten, Buchungen, Belege samt Belegdatei, Kostenstellen	bank.read / bank.manage
beitraege	Sammlungen und Forderungen	bank.read / bank.manage
spenden	Zuwendungsbestätigungen samt PDF	bank.read / bank.manage
fahrtkosten	Fahrtkostenabrechnungen samt Fahrten und PDF	bank.read / bank.manage
bescheinigungen	Vorlagen für Teilnahmebescheinigungen und Sonderurlaub	events.read / events.manage
abrechnung	Abrechnungen, Belege, Einnahmen	abrechnung.read / abrechnung.manage
kalkulation	Budgetplanung, Szenarien, Positionen	kalkulation.read / kalkulation.manage
mails	Nachrichten, Vorlagen, Anhänge, Versand	mail.send / mail.send
dokumente	Ordner und Dateien im Cloudspeicher	documents.read / documents.write
warteliste	Stufen-Wartelisten	– / contacts.manage
hinweise	Meldungen auf dem Dashboard	– / settings.manage
kalender	Termine aus Veranstaltungen, Packlisten und Ausleihen	calendar / kein Schreibweg
stammdaten	Benutzer, Rollen, Rechte, Aktivitätsprotokoll	users.manage / kein Schreibweg

Ein Strich bei „lesen" heißt nicht „ohne Bereich lesbar"

Manche Bereiche haben kein eigenes internes Leserecht, weil sie in der Anwendung für jedes angemeldete Konto sichtbar sind (z. B. der Materialbestand). Ein Schlüssel braucht den Bereich material:read trotzdem – sonst wäre die Bereichsgrenze wirkungslos.

kalender und stammdaten lassen sich gar nicht auf lesen & bearbeiten stellen: Termine entstehen aus den Fachbereichen, und wer über einen Schlüssel Konten oder Rollen ändern könnte, könnte sich damit selbst mehr Rechte verschaffen, als der Schlüssel je hatte.

Endpunkte, die zwei Bereiche verlangen

Drei Endpunkte greifen über ihren eigenen Bereich hinaus. Sie brauchen beide genannten Bereiche:

Endpunkt	Bereiche	Warum
POST /spenden/{id}/als-beleg	spenden:write + bank:write	legt einen Beleg in der Buchhaltung an
POST /fahrtkosten/{id}/als-beleg	fahrtkosten:write + bank:write	legt eine Auslage in der Buchhaltung an
GET /veranstaltungen/{id}/teilnehmer/{tid}/bescheinigung/{vorlagenId}	veranstaltungen:read + bescheinigungen:read	verbindet Teilnahme und Vorlage

Ein Schlüssel, der nur Bestätigungen ausstellen darf, soll keine Belege in der Kasse erzeugen können.

Ein Sonderfall: POST /verleih/pruefen

Dieser Endpunkt ist ein POST, verlangt aber nur verleih:read. Er legt nichts an: Die Verfügbarkeitsprüfung ist ein Nachschlagen mit einer Eingabe, die für eine URL zu lang wäre. In der OpenAPI-Beschreibung trägt er die Markierung x-nur-lesend.

Dokumente: ein Schlüssel sieht alle Ordner

Die Freigaben je Ordner hängen an Benutzerkonten und Rollen. Ein Schlüssel hat weder das eine noch das andere – er kann also nicht „nur die freigegebenen Ordner" sehen. Ein Schlüssel mit dem Bereich dokumente sieht alle Ordner (außer den System-Ordnern der Anwendung), so wie ein Konto mit documents.manage.

Wer nur einzelne Ordner nach außen geben will, nimmt die Freigabelinks der Anwendung, nicht die Schnittstelle.

Was die Schnittstelle bewusst nicht kann

Diese Grenzen sind keine Lücken, sondern Absicht:

• Konten, Rollen und Rechte anlegen oder ändern. Wer das über einen Schlüssel könnte, könnte sich selbst mehr Rechte verschaffen, als der Schlüssel je hatte.
• SSO/OIDC, Zwei-Faktor, SMTP, Speicheranbindung. Dasselbe Argument: das sind die Stellschrauben der Anmeldung selbst.
• Zugangsschlüssel verwalten. Ein Schlüssel, der sich selbst verlängern kann, hat kein Ablaufdatum.
• Kontoauszüge importieren. Der CAMT-Import hat Dubletten-Erkennung, Saldo-Abgleich und Fehlerprotokoll; ein Dateiupload würde die halbe Mechanik umgehen.
• SEPA-Lastschriftdateien erzeugen. Damit wird Geld eingezogen – das bleibt ein bewusster Vorgang in der Anwendung, mit der dortigen Vorschau samt übersprungenen Mandaten.
• Nachweis-Dateien herunterladen. Dass für eine Person ein Führungszeugnis vorliegt, ist ohnehin heikel; die Datei selbst bleibt in der Anwendung.
• Veranstaltungen, Packlisten, Dokumente und Ordner endgültig löschen. DELETE legt sie in den Papierkorb. Ein Tippfehler im Skript soll nichts unwiederbringlich vernichten.
• Ausstellungs-Angaben ändern (Spenden, Fahrtkosten, Bescheinigungen). Lesen ja – ein Werkzeug muss den Kilometersatz kennen, um einen Betrag anzeigen zu können. Ändern nein: daran hängen Logo und Unterschrift als hochgeladene Bilder, die Nummernkreise der Bestätigungen und der Betrag, den der Verein tatsächlich auszahlt.
• Entfernungen berechnen lassen. Der Aufruf der Anwendung fragt einen fremden Kartendienst auf Kosten des Vereins. Ein Skript in einer Schleife hätte das Tageskontingent verbraucht, bevor es jemand merkt; Kilometer lassen sich angeben.
• Spendenbestätigungen löschen. Sie tragen eine fortlaufende Nummer und gehen an das Finanzamt. Es gibt nur den Storno mit Begründung.
• In einem Aufruf anlegen und sofort senden (Mails). Der Versand ist bewusst der ausdrückliche zweite Schritt.

Was es (noch) nicht gibt

Kein Grundsatz, sondern schlicht nicht gebaut:

• Mitgliederportal und Benachrichtigungen – beides hängt an einzelnen Benutzerkonten, und ein Schlüssel gehört keinem Konto.
• Aufbewahrungsfristen und Löschlauf – der Lauf löscht endgültig und startet über die automatischen Abläufe, nicht über einen Aufruf von außen.
• CSV-Import, gespeicherte Filter, Belegerkennung, Freigabelinks, Dashboard-Kennzahlen – Werkzeuge der Oberfläche; ihre Ergebnisse stehen über die Fachbereiche zur Verfügung.