Authentication
Every request needs a key. A key belongs to one association and has its own scopes.
Keys
A key looks like lb_live_ followed by 32 characters. Send it in the Authorization header:
Authorization: Bearer lb_live_3xT9...An administrator creates keys under Settings → API keys. The key is shown once; we only store a hash and the first twelve characters, so you can recognise it in the overview. Lost means lost: create a new key and revoke the old one.
A key can have an expiry date and can be revoked at any time. A revoked or expired key returns invalid_api_key. On the same page the administrator sees the latest requests per key; that log is kept for 90 days.
Never in the URL
A key in the query string, such as ?api_key= or ?access_token=, is rejected with api_key_in_url, even if the key is valid. A URL ends up in server logs, in browser history and in the Referer header sent to other sites. If that happened, revoke the key.
Scopes
When creating a key, the administrator chooses its scopes. Give each integration only what it needs. If a request needs a scope the key does not have, you get insufficient_scope with the missing scope in detail.
| Scope | What the key may do with it |
|---|---|
leden:lezen |
View members, participants and relationships |
leden:schrijven |
Add and update members |
leden:gevoelig |
Also view date of birth, IBAN and mandate |
groepen:lezen |
View groups and committees |
groepen:schrijven |
Add members to groups and remove them |
evenementen:lezen |
View events and registrations |
evenementen:schrijven |
Add registrations |
facturen:lezen |
View invoices and payments |
facturen:schrijven |
Create and send invoices |
Date of birth and bank details (date_of_birth and sepa) are only included with leden:gevoelig.
The scope names are Dutch, like the rest of Ledenboek: leden means members, groepen groups, evenementen events, facturen invoices, lezen read, schrijven write and gevoelig sensitive.
Test keys
A key from a sample association starts with lb_test_. It works at the same address and with the same endpoints as a live key, with two differences:
- no email and no payment requests are sent, not even when you create an invoice;
- the limit is 120 requests per minute instead of 600.
The data of a sample association is made up, so you can try anything.
Subscription
The API is part of the association's subscription. Without a valid subscription every request returns subscription_required (status 402). As soon as the subscription is in order again, the same key works again.
Language of error messages
The title and detail fields of an error follow the Accept-Language header: nl, en, de or fr. Without that header you get English. The type field is the same in every language.