Via de API van Bloxs wisselen systemen automatisch gegevens met elkaar uit. Een externe partij, bijvoorbeeld een leverancier of koppelpartner, krijgt deze toegang via een serviceaccount: een speciaal type account dat wordt gebruikt door applicaties of systemen en niet door individuele gebruikers. Met een serviceaccount vindt communicatie met het Bloxs-platform plaats zonder dat daarvoor persoonlijke gebruikersgegevens nodig zijn.
Dit artikel beschrijft het volledige traject: de API en serviceaccounts activeren, een rol aanmaken, een serviceaccount inrichten voor een leverancier, credentials aanmaken en delen, en toegang weer intrekken.
In het kort bestaat de inrichting uit vijf stappen:
- API en serviceaccounts activeren via Admin > Add-ons en koppelingen > API > Serviceaccounts
- Een rol voor serviceaccounts aanmaken via Admin > Toegangsbeheer > Rollen voor serviceaccounts
- Het leveranciersportaal activeren en het portaal openen voor de betreffende leverancier.
- API-toegang verlenen door een rol toe te wijzen op het tabblad "Portaal".
- De API-credentials aanmaken en via een beveiligd kanaal delen.
Stap 1: API en serviceaccounts activeren
Navigeer naar Admin > Add-ons en koppelingen > API om de API-instellingen te doorlopen.
Bovenaan deze pagina staat de hoofdschakelaar "API's". Staat deze aan, dan worden de beschikbare API's van Bloxs getoond en kunnen deze afzonderlijk van elkaar worden aangezet.
Op dezelfde pagina wordt de optie "Serviceaccounts" aangezet. Daarmee verschijnen in Admin > Toegangsbeheer de onderdelen "Serviceaccounts" en "Rollen voor serviceaccounts".
Verder staan op deze pagina de gegevens die bij een koppeling horen:
- API-secret: de unieke sleutel waarmee de Bloxs-omgeving wordt herkend bij het tot stand brengen van een koppeling. Een bestaande API-secret is in te zien via het oogicoon, kopiëren kan via "Kopiëren" en met "Resetten" wordt een nieuwe API-secret aangemaakt. Let op: na het resetten werken de actieve API-koppelingen niet meer en worden deze opnieuw geconfigureerd met de nieuwe API-secret.
- URL: de API's van de omgeving zijn bereikbaar via een omgevingsspecifieke URL, deze heeft de vorm [klantomgeving].bloxs.io. Voor de OData-feed is dat [klantomgeving].bloxs.io/odatafeed.
Stap 2: een rol voor serviceaccounts aanmaken
Voordat een serviceaccount toegang krijgt, wordt eerst bepaald tot welke onderdelen van Bloxs het toegang mag hebben. Dat gebeurt met een rol: een verzameling permissies die aangeeft welke API-onderdelen gebruikt mogen worden, bijvoorbeeld de Relatie API of de Objecten API, en wat daarbinnen mag, bijvoorbeeld het lezen, bewerken of aanmaken van personen of gebouwen.
Ga naar Admin > Toegangsbeheer > Rollen voor serviceaccounts en klik rechtsboven op "+ rol voor serviceaccounts". Stel vervolgens samen welke permissies de rol krijgt. Kies daarbij alleen de onderdelen die de koppeling echt nodig heeft, zodat de toegang beperkt blijft tot wat de leverancier gebruikt. Eén rol kan daarna aan meerdere serviceaccounts worden toegewezen.
AFBEELDING 1: het scherm voor het aanmaken van een rol voor serviceaccounts, met de permissies per API-onderdeel.
Is er behoefte aan advies over de indeling van rollen en permissies, dan denkt een consultant van Bloxs graag mee tijdens een service management-sessie. Het maken van een afspraak voor servicemanagement kan via deze link: https://support.bloxs.com/support/solutions/articles/80001173815-service-management
Stap 3: het leveranciersportaal activeren
Een serviceaccount wordt aangemaakt voor een relatie van het type "Leverancier", via de relatiekaart van die leverancier op het tabblad "Portaal". Is dit tabblad niet zichtbaar, dan is de portaalfunctie voor leveranciers nog niet actief. Zet deze aan via Admin > Portaalbeheer > Leveranciersportaal met de optie "Leveranciersportaal".
Open daarna op het tabblad "Portaal" van de leverancier het portaal voor deze specifieke leverancier.
Wordt het leveranciersportaal alleen gebruikt om een serviceaccount aan te maken en hoeft de leverancier zelf niet in te loggen, dan kan de welkomstmail met inloggegevens worden verwijderd. Deze mail staat na het openen van het portaal klaar bij de dashboardtegel "Te verzenden".
AFBEELDING 2: het tabblad "Portaal" op de relatiekaart van een leverancier, met de knop om het portaal te openen.
Stap 4: API-toegang verlenen
Nadat het portaal is geactiveerd, verschijnt de optie "API-toegang". Wordt deze ingeschakeld, dan wordt het account van de leverancier aangemerkt als serviceaccount en is het zichtbaar op de pagina Admin > Toegangsbeheer > Serviceaccounts. Op dat moment heeft het serviceaccount nog geen toegang tot endpoints: daarvoor wordt eerst een rol toegewezen.
AFBEELDING 3: het tabblad "Portaal" op de relatiekaart van een leverancier, met de API-toegang geactiveerd.
Wijs de rol toe via de knop "API-toegang verlenen" op het tabblad "Portaal". Vul daarbij het volgende in:
- Omschrijving: waarvoor deze toegang wordt gebruikt.
- Rol: de eerder aangemaakte rol voor serviceaccounts. Is er nog geen rol beschikbaar, maak deze dan eerst aan via Admin > Toegangsbeheer > Rollen voor serviceaccounts.
- Administratie: alleen beschikbaar wanneer administratiegroepen zijn geactiveerd via Admin > Toegangsbeheer > Administratiegroepen.
- API-key zelf aanmaken: bepaalt wie de credentials aanmaakt.
Staat "API-key zelf aanmaken" aan, dan maakt de gebruiker in Bloxs de credentials voor het serviceaccount zelf aan nadat de rol is toegewezen. Staat deze optie uit, dan logt de leverancier in op het leveranciersportaal en maakt daar de credentials aan; in dat geval wordt de eerder genoemde welkomstmail met inloggegevens wél naar de leverancier verstuurd.
In de praktijk wordt vaak gekozen om de credentials zelf aan te maken en deze via een beveiligd kanaal met de leverancier te delen, omdat dit eenvoudiger in te richten is dan de leverancier zelf te laten inloggen.
AFBEELDING 4: het venster "API-toegang verlenen" met de velden omschrijving, rol, administratie en de optie "API-key zelf aanmaken".
Stap 5: credentials aanmaken en delen
Na het klikken op "Toevoegen" verschijnt in de tabel met API-toegang op het tabblad "Portaal" een regel met de toegewezen rol, met daarbij de mogelijkheid om een primaire en een secundaire API-key aan te maken.
Klik bij de primaire of secundaire sleutel op "API-key aanmaken". De credentials worden dan gegenereerd en getoond: een URL, een key en een secret. Deze zijn te kopiëren of gezamenlijk te downloaden als .json-bestand. Zo'n bestand ziet er als volgt uit:
{
"APIUrl": "[url]",
"APIKey": "[key]",
"APISecret": "[secret]"
}
Met deze credentials wordt toegang verkregen tot Bloxs via de API, en daarmee tot alle gegevens die met de toegewezen rol bereikbaar zijn. Deel deze gegevens daarom altijd via een beveiligd kanaal en nooit via e-mail of een ander onbeveiligd kanaal.
AFBEELDING 5: de tabel met API-toegang op het tabblad "Portaal", met de regels voor de primaire en secundaire API-key.
AFBEELDING 6: het scherm met de gegenereerde credentials (URL, key en secret) en de mogelijkheid om deze te kopiëren of als .json-bestand te downloaden.
AFBEELDING 7: de tabel met API-toegang in het leveranciersportaal, met de regels voor de primaire en secundaire API-key.
Waarom een primaire en een secundaire API-sleutel?
Een serviceaccount met API-toegang beschikt over twee sleutels: een primaire en een secundaire. Beide geven exact dezelfde toegang; het verschil zit niet in de rechten, maar in het gebruik.
Met twee sleutels wordt een sleutel vervangen terwijl de koppeling blijft draaien. Een koppeling draait bijvoorbeeld op de primaire sleutel. Wordt de secundaire sleutel opnieuw gegenereerd, dan worden koppelingen daar één voor één op overgezet. Omdat beide sleutels in die periode geldig blijven, is hier alle tijd voor. Zodra alle koppelingen zijn overgezet, wordt de primaire sleutel opnieuw gegenereerd, waarmee de oude waarde direct ongeldig wordt. Bij de volgende rotatie worden de rollen omgedraaid.
Dat levert twee voordelen op: sleutels worden periodiek vernieuwd zonder geplande storing, en bij een vermoeden dat een sleutel is uitgelekt, wordt deze direct ingetrokken terwijl de andere koppelingen blijven werken.
De twee sleutels zijn niet bedoeld om verschillende systemen van elkaar te scheiden: in de logging zijn ze niet van elkaar te onderscheiden, waardoor achteraf niet te zien is welke koppeling wat heeft gedaan. Moeten systemen apart beheerd of ingetrokken kunnen worden, maak dan per systeem een eigen serviceaccount met een eigen sleutelpaar aan.
Toegang intrekken
Gebruik de knop "Toegang intrekken" op het tabblad "Portaal" van de leverancier om de volledige toegang van een serviceaccount in te trekken. Daarmee wordt de toegang tot zowel het leveranciersportaal als de API voor het gehele account geblokkeerd.
Moet niet het hele account maar slechts één API-rol worden geblokkeerd, klik dan in de tabel met API-toegang bij de betreffende rol op het sloticoon ("Blokkeren"). Het serviceaccount heeft dan geen toegang meer via die rol. De rol wordt later weer geactiveerd door opnieuw op het sloticoon te klikken.
De OData-feed via een serviceaccount
Ook de OData-feed is via een serviceaccount te koppelen. Zet daarvoor in Admin > Add-ons en koppelingen > API zowel "Serviceaccounts" als "OData toewijzen aan serviceaccounts" aan. Deze laatste instelling is alleen zichtbaar wanneer "Serviceaccounts" al is geactiveerd.
Maak vervolgens via Admin > Toegangsbeheer > Rollen voor serviceaccounts een rol aan met de permissies uit de sectie "OData-feed". Deze rol wordt daarna op dezelfde manier aan een serviceaccount toegewezen als hierboven beschreven.
Meer informatie
Het serviceaccount heeft nu toegang tot de endpoints die via de toegewezen rollen zijn opengesteld. De technische documentatie van de API staat op https://www.bloxs.io.