Authenticatie
Elke aanroep heeft een sleutel nodig. Een sleutel hoort bij één vereniging en heeft zijn eigen rechten.
Sleutels
Een sleutel ziet eruit als lb_live_ gevolgd door 32 tekens. Je stuurt hem in de header Authorization:
Authorization: Bearer lb_live_3xT9...Een beheerder maakt sleutels aan onder Instellingen → API-sleutels. De sleutel wordt één keer getoond; wij bewaren alleen een hash en de eerste twaalf tekens, zodat je hem in het overzicht terugziet. Kwijt is dus kwijt: maak dan een nieuwe sleutel en trek de oude in.
Een sleutel kan een vervaldatum hebben en kan op elk moment worden ingetrokken. Een ingetrokken of verlopen sleutel geeft invalid_api_key. Op dezelfde pagina ziet de beheerder de laatste aanroepen per sleutel; dat logboek wordt 90 dagen bewaard.
Nooit in de URL
Een sleutel in de querystring, zoals ?api_key= of ?access_token=, weigeren we met api_key_in_url, ook als de sleutel klopt. Een URL belandt in serverlogs, in de geschiedenis van een browser en in de Referer-header naar andere sites. Is dat gebeurd, trek de sleutel dan in.
Rechten
Bij het aanmaken kiest de beheerder welke rechten een sleutel krijgt. Geef elke koppeling alleen wat hij nodig heeft. Vraagt een aanroep een recht dat de sleutel niet heeft, dan krijg je insufficient_scope met het ontbrekende recht in detail.
| Recht | Wat de sleutel daarmee mag |
|---|---|
leden:lezen |
Leden, deelnemers en relaties bekijken |
leden:schrijven |
Leden toevoegen en bijwerken |
leden:gevoelig |
Ook geboortedatum, IBAN en machtiging bekijken |
groepen:lezen |
Groepen en commissies bekijken |
groepen:schrijven |
Leden aan groepen toevoegen en eruit halen |
evenementen:lezen |
Evenementen en inschrijvingen bekijken |
evenementen:schrijven |
Inschrijvingen toevoegen |
facturen:lezen |
Facturen en betalingen bekijken |
facturen:schrijven |
Facturen aanmaken en versturen |
Geboortedatum en rekeninggegevens (date_of_birth en sepa) komen alleen mee met leden:gevoelig.
Testsleutels
Een sleutel van een voorbeeldvereniging begint met lb_test_. Hij werkt op hetzelfde adres en met dezelfde endpoints als een live sleutel, met twee verschillen:
- er gaan geen mails en geen betaalverzoeken de deur uit, ook niet als je een factuur aanmaakt;
- de limiet is 120 aanroepen per minuut in plaats van 600.
De gegevens van een voorbeeldvereniging zijn verzonnen, dus je kunt er alles mee proberen.
Abonnement
De API hoort bij het abonnement van de vereniging. Zonder geldig abonnement geeft elke aanroep subscription_required (status 402). Zodra het abonnement weer in orde is, werkt dezelfde sleutel weer.
Taal van foutmeldingen
De velden title en detail van een fout volgen de header Accept-Language: nl, en, de of fr. Zonder die header krijg je Engels. Het veld type is in elke taal hetzelfde.