API / Bewerken
Laatst bijgewerkt: 09-11-2026
Met een API-sleutel geef je je eigen software toegang tot Spreash®. Op deze pagina maak je een sleutel aan, vernieuw je hem en trek je hem weer in.
In dit artikel leer je:
- Een API-sleutel aanmaken en kiezen voor welke modules en in welke vorm (lezen of schrijven) hij werkt
- Kiezen tussen een persoonlijke en een accountbrede API-sleutel
- Het geheim van een sleutel vernieuwen voordat hij verloopt
- Een toegangstoken aanvragen, de API aanroepen en de API uitproberen in je browser
- De toegang van een sleutel intrekken
Kernconcepten
Voordat je aan de slag gaat, is het handig om de volgende type objecten te kennen.
API-sleutel — geeft je eigen software toegang tot Spreash®. De sleutel werkt namens jou, met de rechten die je hem geeft, en nooit met meer rechten dan je zelf hebt.
Modulerechten — bepalen voor welke modules en in welke vorm (lezen of schrijven) een sleutel de API mag gebruiken. De API is alleen beschikbaar voor de modules en in de vorm die je bij het aanmaken van een sleutel kunt selecteren.
Persoonlijke API-sleutel — hoort bij de gebruiker die hem heeft aangemaakt. Elke gebruiker ziet alleen de eigen sleutels. De sleutel werkt niet meer als die gebruiker vertrekt.
Accountbrede API-sleutel — hoort bij het account en werkt alleen met zijn eigen rechten. Gebruik hem voor een koppeling die moet blijven werken als degene die hem heeft ingesteld vertrekt.
Modulerechten — bepalen voor welke modules en in welke vorm (lezen of schrijven) een sleutel de API mag gebruiken. De API is alleen beschikbaar voor de modules en in de vorm die je bij het aanmaken van een sleutel kunt selecteren.
Client-ID — de naam van je sleutel voor de API. Hij blijft op de kaart van de sleutel staan, waar je hem altijd opnieuw kunt kopiëren.
Clientgeheim — het wachtwoord van je sleutel. Spreash® toont het maar één keer.
Toegangstoken — wat je koppeling krijgt in ruil voor de client-ID en het clientgeheim. Een toegangstoken is 10 uur geldig.
- Endpoint — een adres in de API waar je gegevens kunt opvragen of wijzigen.
- ReDoc — de naslag van de API. Hier lees je alle endpoints, met hun parameters en antwoorden.
- Swagger — de API uitproberen in je browser, zonder zelf code te schrijven.
API-sleutel toevoegen — maakt een nieuwe sleutel aan.
Geheim vernieuwen — geeft de sleutel een nieuw clientgeheim en verlengt hem.
Verwijderen — trekt de toegang van de sleutel direct in.
Verloopt binnenkort / Verlopen — labels op de kaart van een sleutel. Verloopt binnenkort verschijnt in de laatste 14 dagen voordat de sleutel verloopt.
Video walkthrough
[Link video volgt.]
API-sleutels bewerken
Heb je nog geen API-sleutel, dan begin je hier met je eerste sleutel.
API-sleutel toevoegen
Volg de onderstaande stappen om een persoonlijke of een accountbrede API-sleutel toe te voegen. De stappen zijn voor beide soorten gelijk. Het verschil zit in wie de sleutel bezit en in de rechten die je nodig hebt.
Let op: Je hebt het recht nodig om de soort sleutel aan te maken die je wilt:
- Persoonlijke API-sleutel — het recht om persoonlijke API-sleutels aan te maken. Een accountbeheerder geeft dat recht aan een groep onder API-toegang op de pagina Groepen.
- Accountbrede API-sleutel — het recht om accountbrede API-sleutels te beheren.
Let op: Een sleutel werkt alleen voor de modules en in de vorm (lezen of schrijven) die je in het paneel kunt selecteren. Wat je daar niet kunt selecteren, is niet beschikbaar via de API.
- Open rechtsboven het profielmenu en kies API-sleutels.
- Schakel linksboven met de schakelaar Bekijken/Bewerken naar Bewerken.
- Kies de soort sleutel. Mag je beide soorten aanmaken, dan toont de pagina de tabbladen Persoonlijk en Accountbreed. Open het tabblad Persoonlijk voor een persoonlijke sleutel, of het tabblad Accountbreed voor een accountbrede sleutel.
- Klik op API-sleutel toevoegen. Er opent een paneel.
- Geef de sleutel een naam waaraan je herkent welke koppeling hem gebruikt, bijvoorbeeld “Laadproces datawarehouse”.
- Beschrijf eventueel wat de koppeling doet. Typ in de omschrijving # om een definitie te noemen die de koppeling leest of schrijft.
- Kies onder Geldig voor hoe lang de sleutel werkt: 30 dagen, 90 dagen, 180 dagen of 1 jaar.
- Vink de organisaties en domeinen aan die de koppeling nodig heeft.
- Kies de modules die de koppeling nodig heeft, en per module of de koppeling mag lezen, schrijven of beide.
- Klik op Aanmaken. Spreash® toont de client-ID en het clientgeheim (grijze vlak in de afbeelding).
- Kopieer beide en bewaar ze op een veilige plek, zoals de geheimenopslag van je koppeling.
- Open rechtsboven het profielmenu en kies API-sleutels.




Persoonlijk of accountbreed: het verschil
Een persoonlijke en een accountbrede sleutel werken hetzelfde. Ze verschillen op deze punten:
- Eigenaar — een persoonlijke sleutel hoort bij de gebruiker die hem aanmaakte en werkt niet meer als die gebruiker vertrekt. Een accountbrede sleutel hoort bij het account en blijft werken. De kaart van een accountbrede sleutel toont wie hem heeft aangemaakt.
- Zichtbaarheid — elke gebruiker ziet alleen de eigen persoonlijke sleutels. Laat collega’s dus hun eigen sleutel aanmaken in plaats van de jouwe te delen.
- Rechten van de sleutel — een persoonlijke sleutel doet nooit meer dan jij zelf kunt. Verlies je een recht dat de sleutel heeft, dan verliest de sleutel het ook, tot je het terugkrijgt. De kaart van de sleutel meldt dan welk deel niet werkt. Een accountbrede sleutel werkt alleen met zijn eigen rechten.
- Wijzigen en verwijderen — een accountbrede sleutel kan alleen worden gewijzigd of verwijderd door iemand die alle rechten van die sleutel zelf heeft.
- Waarschuwingen — accountbrede sleutels die verlopen zijn of binnen 14 dagen verlopen, staan ook op het Accountdashboard, in de kaart API-sleutels. Je ziet ze daar als je accountbrede API-sleutels mag beheren.
Controleren wanneer een sleutel verloopt
Elke API-sleutel verloopt, uiterlijk een jaar nadat hij is aangemaakt of zijn geheim voor het laatst is vernieuwd. De kaart van de sleutel toont wanneer hij verloopt.
- Verloopt binnenkort — de sleutel verloopt binnen 14 dagen.
- Verlopen — de sleutel is verlopen. Een verlopen sleutel krijgt geen nieuwe toegangstokens, en de toegangstokens die hij al heeft werken niet meer.
Een API-sleutel vernieuwen of verwijderen
Gebruik het menu op de kaart van de sleutel. Je ziet het menu alleen in de bewerkmodus.
- Geheim vernieuwen — geeft de sleutel een nieuw clientgeheim. Gebruik dit om een sleutel te laten blijven werken, of om een geheim te vervangen dat mogelijk is uitgelekt.
- Verwijderen — trekt de toegang van de sleutel direct in.
Het geheim vernieuwen
Volg de onderstaande stappen om het geheim van een sleutel te vernieuwen.
- Ga naar API-sleutels via het profielmenu rechtsboven en schakel naar Bewerken.
- Open de sleutel en kies Geheim vernieuwen in het menu op de kaart.
- Kies onder Oud geheim blijft werken hoe lang je koppeling het oude geheim nog mag gebruiken terwijl je overstapt: nu stoppen, 1 uur, 24 uur of 7 dagen.
- Kies onder Geldig voor hoe lang de sleutel vanaf nu werkt.
- Klik op Vernieuwen. Spreash® toont het nieuwe clientgeheim, één keer. De client-ID blijft gelijk.
- Zet het nieuwe geheim in je koppeling voordat het oude stopt.
Een API-sleutel verwijderen
Volg de onderstaande stappen om de toegang van een sleutel in te trekken.
- Ga naar API-sleutels via het profielmenu rechtsboven en schakel naar Bewerken.
- Open het menu op de kaart van de sleutel en kies Verwijderen.
- Bevestig het verwijderen als Spreash® daarom vraagt.
Elk toegangstoken van de sleutel werkt daarna direct niet meer. De toegang stopt ook als de sleutel verloopt, als je gebruiker wordt gedeactiveerd of als je account wordt opgeschort.
De API-sleutel gebruiken
Je sleutel werkt alleen voor de modules en in de vorm (lezen of schrijven) die je bij het aanmaken hebt aangevinkt. Een aanroep voor een andere module, of in een andere vorm, wordt geweigerd.
Een toegangstoken aanvragen
Volg de onderstaande stappen om een toegangstoken aan te vragen. Je koppeling doet dit zelf, met de OAuth 2.0-grant client credentials.
- Ruil de client-ID en het clientgeheim in bij het tokenadres:
curl -u "<client-ID>:<clientgeheim>" \
-d grant_type=client_credentials \
https://<jouw Spreash®-adres>/oauth2/token/Het antwoord bevat het toegangstoken:
{"access_token": "spreash_…", "expires_in": 36000, "token_type": "Bearer", "scope": "read write"}Is het toegangstoken na 10 uur verlopen, vraag dan op dezelfde manier een nieuw token aan.
De API aanroepen
Volg de onderstaande stappen om de API aan te roepen.
- Stuur het toegangstoken mee in de Authorization-header van elk verzoek:
curl -H "Authorization: Bearer <toegangstoken>" \
https://<jouw Spreash®-adres>/api/v1/me/- Controleer of je sleutel werkt. /api/v1/me/ geeft de API-sleutel terug waarmee het token werkt, en het account ervan.
De API verkennen en uitproberen
Alle endpoints, met hun parameters en antwoorden, staan in de API-documentatie. Je vindt de documentatie op twee adressen: ReDoc om te lezen, Swagger om uit te proberen.
De naslag lezen in ReDoc
Volg de onderstaande stappen om de naslag van de API te lezen.
- Ga naar https://<jouw Spreash®-adres>/api/v1/redoc/.
- Zoek het endpoint dat je koppeling nodig heeft.
- Lees welke parameters het endpoint heeft en welke antwoorden het geeft.

De API uitproberen met Swagger
Volg de onderstaande stappen om de API in je browser uit te proberen, zonder zelf code te schrijven.
Let op: Een aanroep in Swagger is een echte aanroep, met de rechten van de sleutel waarmee je je aanmeldt. Roep je een endpoint aan dat gegevens wijzigt, dan worden die gegevens ook echt gewijzigd.
- Ga naar https://<jouw Spreash®-adres>/api/v1/swagger/.
- Klik op Authorize.
- Vul bij oauth2 (OAuth2, clientCredentials) de client-ID en je clientgeheim in (cookieAuth (apiKey) is niet relevant).
- Bevestig je invoer en sluit het venster.
- Kies een endpoint. Probeer als eerste /api/v1/me/. Dat geeft de API-sleutel terug waarmee je bent aangemeld, en is een snelle manier om te controleren dat je sleutel werkt.
- Vul de parameters in en voer de aanroep uit.
- Bekijk het antwoord van Spreash®.


Veelvoorkomende situaties
- Ik ben het clientgeheim kwijt, of mijn geheim is mogelijk uitgelekt.
Spreash® toont het clientgeheim maar één keer, dus een kwijt geheim kun je niet terugzien. Vernieuw het geheim om een nieuw clientgeheim te krijgen. De client-ID blijft gelijk. Is het geheim mogelijk uitgelekt, kies dan onder Oud geheim blijft werken voor Nu stoppen. De toegangstokens die met het oude geheim zijn uitgegeven werken dan ook niet meer. - Mijn koppeling krijgt geen toegang meer.
Een toegangstoken is 10 uur geldig. Vraag op dezelfde manier een nieuw toegangstoken aan en laat je koppeling dit automatisch doen. Staat de sleutel op Verlopen, dan verloopt elke sleutel uiterlijk een jaar nadat hij is aangemaakt of zijn geheim voor het laatst is vernieuwd. Vernieuw het geheim en zet het nieuwe geheim in je koppeling. De toegang stopt ook als de sleutel is verwijderd, als je gebruiker wordt gedeactiveerd of als je account wordt opgeschort. Neem dan contact op met een accountbeheerder. Hoorde de sleutel bij een collega die is vertrokken, dan werkt hij niet meer. Maak voor de koppeling een accountbrede API-sleutel aan. - Ik kan een organisatie, een domein of een modulerecht niet aanvinken, of ik mis een module of de vorm lezen of schrijven.
Je kunt een sleutel alleen rechten geven die je zelf hebt. Vraag een accountbeheerder om het recht. De API is bovendien alleen beschikbaar voor de modules en in de vorm die je in het paneel kunt selecteren. Wat je niet kunt selecteren, is niet beschikbaar via de API. - Een persoonlijke sleutel heeft ineens minder rechten.
Een persoonlijke sleutel doet nooit meer dan jij zelf kunt. Verlies je een recht, dan verliest de sleutel het ook. Krijg je het recht terug, dan werkt dat deel van de sleutel weer. De kaart van de sleutel meldt welk deel niet werkt. - Ik kan een accountbrede sleutel niet wijzigen of verwijderen.
Een accountbrede sleutel kan alleen worden gewijzigd of verwijderd door iemand die alle rechten van die sleutel zelf heeft. Vraag iemand die alle rechten van de sleutel heeft om de wijziging door te voeren.
Gerelateerde pagina's
- API-sleutels / Bekijken — de sleutels en hun verloopdatum bekijken.
- Gebruikersbeheer / Bewerken — het recht API-toegang aan een groep geven.
- Account-dashboard / Bekijken — de kaart API-sleutels met sleutels die verlopen zijn of binnenkort verlopen.
