Authentifizierung

Jeder Aufruf braucht einen Schlüssel. Ein Schlüssel gehört zu einem Verein und hat eigene Rechte.

Schlüssel

Ein Schlüssel sieht aus wie lb_live_, gefolgt von 32 Zeichen. Sie senden ihn im Header Authorization:

HTTP

Authorization: Bearer lb_live_3xT9...

Ein Administrator erstellt Schlüssel unter Einstellungen → API-Schlüssel. Der Schlüssel wird einmal angezeigt; wir speichern nur einen Hash und die ersten zwölf Zeichen, damit Sie ihn in der Übersicht wiedererkennen. Verloren heißt verloren: Erstellen Sie dann einen neuen Schlüssel und widerrufen Sie den alten.

Ein Schlüssel kann ein Ablaufdatum haben und jederzeit widerrufen werden. Ein widerrufener oder abgelaufener Schlüssel liefert invalid_api_key. Auf derselben Seite sieht der Administrator die letzten Aufrufe pro Schlüssel; dieses Protokoll wird 90 Tage aufbewahrt.

Nie in der URL

Einen Schlüssel im Query-String, etwa ?api_key= oder ?access_token=, lehnen wir mit api_key_in_url ab, auch wenn der Schlüssel gültig ist. Eine URL landet in Serverprotokollen, im Browserverlauf und im Referer-Header an andere Websites. Ist das passiert, widerrufen Sie den Schlüssel.

Rechte

Beim Erstellen wählt der Administrator die Rechte eines Schlüssels. Geben Sie jeder Anbindung nur, was sie braucht. Verlangt ein Aufruf ein Recht, das der Schlüssel nicht hat, bekommen Sie insufficient_scope mit dem fehlenden Recht in detail.

Recht	Was der Schlüssel damit darf
`leden:lezen`	Mitglieder, Teilnehmer und Beziehungen ansehen
`leden:schrijven`	Mitglieder hinzufügen und ändern
`leden:gevoelig`	Auch Geburtsdatum, IBAN und Mandat ansehen
`groepen:lezen`	Gruppen und Ausschüsse ansehen
`groepen:schrijven`	Mitglieder zu Gruppen hinzufügen und entfernen
`evenementen:lezen`	Veranstaltungen und Anmeldungen ansehen
`evenementen:schrijven`	Anmeldungen hinzufügen
`facturen:lezen`	Rechnungen und Zahlungen ansehen
`facturen:schrijven`	Rechnungen erstellen und versenden

Geburtsdatum und Bankdaten (date_of_birth und sepa) kommen nur mit leden:gevoelig mit.

Die Namen der Rechte sind niederländisch, wie der Rest von Ledenboek: leden heißt Mitglieder, groepen Gruppen, evenementen Veranstaltungen, facturen Rechnungen, lezen lesen, schrijven schreiben und gevoelig sensibel.

Testschlüssel

Ein Schlüssel eines Beispielvereins beginnt mit lb_test_. Er funktioniert unter derselben Adresse und mit denselben Endpunkten wie ein Live-Schlüssel, mit zwei Unterschieden:

es werden keine E-Mails und keine Zahlungsaufforderungen verschickt, auch nicht, wenn Sie eine Rechnung erstellen;
das Limit liegt bei 120 Aufrufen pro Minute statt 600.

Die Daten eines Beispielvereins sind erfunden, Sie können also alles damit ausprobieren.

Abonnement

Die API gehört zum Abonnement des Vereins. Ohne gültiges Abonnement liefert jeder Aufruf subscription_required (Status 402). Sobald das Abonnement wieder in Ordnung ist, funktioniert derselbe Schlüssel wieder.

Sprache der Fehlermeldungen

Die Felder title und detail eines Fehlers folgen dem Header Accept-Language: nl, en, de oder fr. Ohne diesen Header bekommen Sie Englisch. Das Feld type ist in jeder Sprache gleich.