API-tokens

• Wat is een API-token?
• Voorwaarden
• Waar vind ik de API-tokens?
• Een token aanmaken
• Het token wordt maar één keer getoond
• Wat de tokenlijst laat zien
• Een token intrekken
• Het token gebruiken

Wat is een API-token?

Met de Klubraum REST API kunnen je eigen scripts, je verenigingswebsite of andere tools werken met de agenda-evenementen en de leden van je vereniging. Elk verzoek identificeert zich daarbij met een personal access token dat je in de Klubraum-app aanmaakt.

Zo’n token hoort altijd bij één Klubraum en bij de persoon die het heeft aangemaakt. Het heeft alleen de scopes die je het geeft, het kan verlopen en je kunt het op elk moment intrekken. En vooral: een token kan nooit meer dan jij zelf. Bij elk verzoek worden ook je actuele rechten in de app gecontroleerd. Verlies je een recht, dan verliest het token dat ook.

Voorwaarden

• Je bent beheerder van de Klubraum. Andere leden zien deze functie niet.
• Je vereniging heeft een passend abonnement: de ledenlijst, uitnodigingen en het verwijderen van leden zitten in Plus, elk ander endpoint vereist Pro. Zonder passend abonnement verschijnt er een melding over upgraden zodra je op de tegel tikt.

Waar vind ik de API-tokens?

Open de Instellingen en ga naar Huidige Klubraum. De tweede tegel daar heet API-tokens, met de ondertitel Personal access tokens voor de Klubraum API – direct onder de tegel om de naam van je vereniging te wijzigen.

Let op: De tegel direct daaronder hoort bij het token voor aanmeldverzoeken. Dat is een ander token, dat alleen bedoeld is voor het aanmeldformulier op je verenigingswebsite – meer daarover lees je in Aanmeldknop op verenigingswebsite.

Een token aanmaken

Tik rechtsboven op de + (Token aanmaken). Het dialoogvenster API-token aanmaken vraagt je om drie dingen.

Naam

Vrije tekst van maximaal 100 tekens, bijvoorbeeld “Website-sync”. Geef elke tool een eigen token en noem het naar die tool – dan weet je later precies welk token je mag intrekken.

Scopes

Hier bepaal je wat het token mag. Er zijn vier scopes:

• members:read – de ledenlijst lezen.
• members:write – leden uitnodigen en verwijderen.
• events:read – agenda-evenementen lezen.
• events:write – agenda-evenementen aanmaken, wijzigen, afzeggen en verwijderen.

Een schrijfscope omvat altijd ook de bijbehorende leesscope. Zodra je members:write aanvinkt, wordt members:read automatisch mee aangevinkt en kun je het niet meer uitvinken; opgeslagen wordt dan alleen de schrijfscope. Hetzelfde geldt voor events:write en events:read. Er is minstens één scope vereist.

Tip: Kies zo min mogelijk scopes. Een script dat jullie evenementen alleen op je website toont, heeft genoeg aan events:read.

Verloopt na

Kies 30, 90, 180 of 365 dagen – of Nooit. Bij Nooit verschijnt er een waarschuwing, en terecht: een token zonder vervaldatum blijft geldig totdat iemand het intrekt. Geef een token daarom zo mogelijk een beperkte levensduur.

Tik daarna op Aanmaken.

Het token wordt maar één keer getoond

Direct na het aanmaken toont de app het volledige token – de lange geheime tekenreeks die met klubraum_pat_ begint. Kopieer die met de kopieerknop en zet hem meteen op de plek waar je script of tool hem uitleest, het liefst in een wachtwoordmanager of een secrets-opslag.

Belangrijk: Dit is het enige moment waarop de geheime tekenreeks zichtbaar is. Hij kan later niet meer worden opgehaald, ook niet door ons. Ben je hem kwijt, trek het token dan in en maak een nieuw token aan.

Zet de geheime tekenreeks nooit op een openbare plek: niet in de JavaScript van je website, niet in een openbare repository en niet in een verenigingsconversatie. Wie hem heeft, kan de API gebruiken met precies de scopes die jij het token hebt gegeven.

Wat de tokenlijst laat zien

Op het scherm zie je alle tokens van je Klubraum. Bij elk token vind je:

• de naam die je hebt gegeven,
• een korte prefix die met klubraum_pat_ begint en het token aanduidt zonder de geheime tekenreeks prijs te geven,
• de scopes als chips,
• wanneer het is aangemaakt, wanneer het verloopt en wanneer het voor het laatst is gebruikt.

Aan de datum van het laatste gebruik zie je goed welke tokens niemand meer nodig heeft. Ingetrokken tokens blijven in de lijst staan en worden doorgestreept weergegeven.

Een token intrekken

Tik bij het betreffende token op het verwijderpictogram (Token intrekken) en bevestig met Ja, intrekken. Het intrekken geldt onmiddellijk: vanaf dat moment wordt elk verzoek met dit token geweigerd. Ongedaan maken kan niet – een ingetrokken token kan niet opnieuw worden geactiveerd.

Tip: Wil je een token vervangen dat nog in gebruik is? Maak dan eerst het nieuwe token aan, zet je script of tool erop over en trek pas daarna het oude token in.

Het token gebruiken

Stuur het token bij elk verzoek als bearer token mee in de Authorization-header:

Authorization: Bearer klubraum_pat_…

Welke endpoints er zijn, welke parameters ze verwachten en wat ze teruggeven, staat in het ontwikkelaarsgedeelte en in de interactieve API-referentie. In het Engels.