Berechtigungen

Die API wendet dieselben Regeln an wie das Admin-Panel. Ein Token darf über die API genau das, was seine Inhaber:in im Admin-Panel darf: nicht mehr und, bei einem Token, das nur lesen darf, weniger.

Jede Anfrage durchläuft drei Prüfungen:

1. Der Scope des Tokens. Darf dieses Token nur lesen oder auch schreiben? Siehe Authentifizierung.
2. Die Rollen der Inhaber:in. Darf diese Person oder dieser Service-Account diese Art von Endpunkt überhaupt verwenden?
3. Der Datensatz. Darf sie oder er dieses Angebot, dieses Konto oder diese Anmeldung sehen oder ändern? Darüber entscheiden dieselben Prüfungen wie im Admin-Panel, zum Beispiel, ob eine Veranstalter:in ein bereits veröffentlichtes Angebot noch bearbeiten darf.

Rollen und Endpunkte

Admins bestehen jede Prüfung auf ROLE_HOST, Super-Admins jede Prüfung. Bei den übrigen Admins sind die Rollen für Teilnehmer:innen und Zahlungen getrennt: Ein Admin ohne Teilnehmer:innen kann die Endpunkte der Teilnehmer:innen nicht verwenden, einer ohne Zahlungen sieht keine Belege.

ROLE_PARTICIPANTS_ADMIN, ROLE_PAYMENTS_ADMIN und ROLE_CMS_ADMIN zählen nur zusammen mit ROLE_ADMIN oder ROLE_SUPER_ADMIN, bei einer Kolleg:in genauso wie bei einem Service-Account. Bei jedem anderen Konto geben sie keine Rechte. Ohne ROLE_PARTICIPANTS_ADMIN nennt ein Konto seine Teilnehmer:innen nur mit der uuid. Ohne ROLE_PAYMENTS_ADMIN hat es keinen debtor.

Eine Anfrage, die die Prüfung der Rolle nicht besteht, beantwortet die API mit 403 Forbidden.

Was Veranstalter:innen sehen

Veranstalter:innen (ROLE_HOST ohne ROLE_ADMIN) sehen wie im Admin-Panel ihren eigenen Teil des Programms:

• Angebote der Veranstalter-Profile, deren Mitglied sie sind, und jedes Angebot, das direkt mit ihnen geteilt wurde. Sonst nichts, auch nicht die veröffentlichten Angebote anderer Veranstalter-Profile: Dafür rufen Sie die API ohne Token auf. Sie können Angebote anlegen und kopieren, solange die Phase host_editing_stage der Saison aktiv ist. In dieser Zeit können sie auch ihre Angebote ändern (und ihre Wartelisten wieder auffüllen) und Angebote ohne Anmeldungen löschen, bis die Angebote geprüft oder veröffentlicht sind. Angebote durch die Veröffentlichung führen können sie nur, wenn die Saison Veranstalter:innen das Veröffentlichen erlaubt.
• Veranstalter-Profile, deren Mitglied sie sind. Sie können diese ändern, aber keine Veranstalter-Profile anlegen oder löschen.
• Einladungen in ihre Veranstalter-Profile. Sie können Kolleg:innen einladen, Einladungen erneut verschicken und zurückziehen.
• Anmeldungen für ihre Angebote, aber nur, solange die Phase publish_lists der Saison aktiv ist. Ist diese Phase alwaysActive, nur bis zum Ablauf der Aufbewahrungsfrist nach dem letzten Termin des Angebots. Sie müssen immer das Angebot nennen (?offer= oder /offers/{uuid}/attendances). Verlangt die Saison von Veranstalter:innen eine Vertraulichkeitserklärung, sehen sie vor deren Unterzeichnung keine Anmeldungen. Sie sehen die Anmeldungen, die ihre Teilnahmeliste im Admin-Panel zeigt. Das hängt von der Saison und der Installation ab; die Regeln stehen unter Teilnahmeliste eines Angebots. Ob sie Anmeldungen bestätigen, auf die Warteliste setzen, ändern oder auf ein anderes Angebot verschieben dürfen, hängt von der Konfiguration der Installation ab. Anmeldungen anlegen und abmelden dürfen nur Admins.
• Suchergebnisse, beschränkt auf ihre eigenen Angebote und Veranstalter-Profile.

„Nicht gefunden“ heißt „nicht gefunden oder nicht Ihres“

Fragen Sie einen einzelnen Datensatz ab, den Sie nicht sehen dürfen, antwortet die API mit 404 Not Found, nicht mit 403. Sie bestätigt nicht, dass der Datensatz existiert. Die Meldung sagt das auch:

{
  "type": "/errors/404",
  "title": "An error occurred",
  "status": 404,
  "detail": "No offer with this identifier, or none you may see."
}

Listen lassen Datensätze, die Sie nicht sehen dürfen, weg. Die einzige Ausnahme ist die Teilnahmeliste eines Angebots: Dürfen Sie sie noch nicht sehen oder erst nach der Vertraulichkeitserklärung der Saison, lautet die Antwort 403.

Maskierte personenbezogene Daten

Bei Installationen mit mehreren Mandanten sehen globale Admins nicht die personenbezogenen Daten der Personen jedes Mandanten. Die API folgt denselben Regeln wie das Admin-Panel. Datensätze, deren personenbezogene Daten Sie nicht sehen dürfen, tragen "piiMasked": true:

• Dürfen Sie die Person überhaupt nicht sehen, fehlen Namen, E-Mail-Adressen, Telefonnummern und Anschriften. Referenzen auf sie enthalten nur die uuid.
• Dürfen Sie die Identität sehen, aber nicht die Kontaktdaten, steht der Name in der Antwort. E-Mail-Adresse, Telefonnummern und Anschriften fehlen.

{
  "uuid": "0191c7b2-4d5e-7f60-8a1b-2c3d4e5f6a05",
  "roles": ["ROLE_MEMBER"],
  "participants": [{ "uuid": "0191c7b3-1f2a-7c4d-8e5f-6a7b8c9d0e06" }],
  "piiMasked": true
}

Innerhalb Ihres eigenen Mandanten sehen Sie alles, was Ihre Rollen erlauben, und piiMasked ist false.

Ein Beleg mit "piiMasked": true ist schreibgeschützt. Bezahlen oder Verwerfen, Stornieren und Korrigieren lehnt die API mit 403 ab. Dasselbe gilt für das Anlegen eines Belegs für eine Familie, deren Angaben Sie maskiert sehen.

Außerhalb Ihres eigenen Mandanten finden Suchen keine Personen, weil ein Treffer verriete, was ein maskierter Wert sagt:

• q findet bei Konten, Teilnehmer:innen und Debitor:innen nichts, ebenso email bei Konten.
• q bei Belegen durchsucht nur die Belegnummer.
• account als E-Mail-Adresse findet nichts. Eine UUID funktioniert weiter.
• GET /search liefert keine Teilnehmer:innen und keine Konten, Belege nur nach Nummer.
• Die Listen der Konten, Teilnehmer:innen und Debitor:innen sind nach Anlage sortiert, nicht nach Name.