Handleiding koppeling externe partijen

Inhoudsopgave

- Introductie
- Aanmaken van een gebruiker
- Consent flow (wat is dat?)
- api@loket.nl
- Wat zijn activities/endpoints
- Developer portal

Introductie

Gegevensuitwisseling tussen Loket en een andere applicatie kan eenvoudig en veilig middels onze RESTful API. In dit artikel behandelen we de stappen welke hierbij van belang zijn.

API staat voor Application Programming Interface. Een API is een set definities en protocollen voor het bouwen en integreren van applicatiesoftware. Er wordt soms naar verwezen als een contract tussen een informatieaanbieder (bijvoorbeeld Loket.nl) en een informatiegebruiker (de externe koppel partij).

Met andere woorden, als men wil communiceren met een computer of systeem om informatie op te halen of een functie uit te voeren, helpt een API u om aan dat systeem te communiceren wat u wilt, zodat het verzoek begrepen en uitgevoerd kan worden.

Je kunt een API dus zien als een bemiddelaar maar het is ook een manier voor een organisatie om bronnen en informatie te delen met behoud van beveiliging, controle en authenticatie, om te bepalen wie toegang krijgt tot wat.

Aanmaken van een gebruiker

Men kan een koppeling (externe partij) toegang verlenen tot gegevens in Loket. Deze toegang loopt via een gebruiker welke men bij voorkeur op werkgeversniveau aanmaakt. Deze gebruiker krijgt een bepaalde set aan rechten welke afhankelijk zijn van welke gegevens er middels de koppeling worden uitgewisseld. Een gebruiker moet aan de volgende specificaties voldoen:

• De gebruiker moet een normale gebruiker zijn (nadrukkelijk geen webservicegebruiker) die speciaal wordt aangemaakt voor de koppeling en nergens anders voor wordt gebruikt.
• De gebruiker moet actief zijn (niet geblokkeerd).
• De gebruiker moet toegang hebben tot de werkgever.
• De gebruiker moet de juiste rechten hebben. Deze rechten verschillen per koppeling. De juiste rechten kan je hier vinden: https://www.loket.nl/koppelingsrechten/

Aanvullende zaken

• Een gebruiker kan aangemaakt worden op werkgeverniveau en op AK-niveau (providerniveau). Wij raden altijd aan om de gebruiker op werkgeverniveau aan te maken want bij een AK-gebruiker is er sprake van een team waaronder meerdere werkgevers kunnen hangen welke mogelijk niets met elkaar te maken hebben. Dit is een extra voorzorgsmaatregel om te voorkomen dat onbedoeld gegevens van werkgever A inzichtelijk zijn voor werkgever B. In principe is dit afgedekt aan de kant van de externe partij maar Loket heeft geen inzicht en rechten over de werkwijze van een externe partij. In sommige gevallen is een AK-gebruiker wel gewenst zoals bij de koppeling met ASR (via BenefitsPlaza) of bij VCSW / De Goudse. Dit soort koppelingen kent een extra validatie op bijvoorbeeld het werkgeverId om de werkgevers te onderscheiden.
• Gebruikersbeheer en het toekennen van rechten is aan de accountant en/of de werkgever.
• Het eenmalig toestemming geven voor gebruik koppeling loopt via de consent flow.

Extra: nieuwe gebruiker versus bestaande gebruiker

Het is prima mogelijk om een reeds bestaande Loket gebruiker te gebruiken ten behoeve van een API koppeling, zolang deze maar voldoet aan de gestelde voorwaarden.

In de praktijk zien we echter vaak dat men er voor kiest een aparte gebruiker aan te maken t.b.v. een koppeling. Dit heeft als voordeel dat dit dan meer inzichtelijk is voor de gebruikersbeheerder. Het komt dan bijvoorbeeld minder vaak voor dat een koppeling onbedoeld zijn toegang verliest omdat iemand uit dienst gaat.

Consent flow (wat is dat?)

Door middel van een ‘OAuth consent flow’ geef je een derde partij toestemming (=consent) om namens jouw gebruiker gegevens op te halen dan wel te bewerken.

Een dergelijke flow herken je misschien van Facebook, Google e.d.

Dit is een extra veilige manier om een derde partij gericht toegang te geven tot (een deel van) jouw gegevens.

Wanneer

In het geval van Loket is deze consent flow vooral van toepassing bij het activeren van API koppelingen, die gebouwd zijn door een vertrouwde derde partij.

Hoe

Dit artikel laat zien hoe deze flow er standaard uit ziet, zodat je weet wat je kan verwachten als je deze in de praktijk nodig hebt voor het activeren van een koppeling.

Houd er rekening mee dat bij iedere koppeling de precieze implementatie zal verschillen. Daarvoor verwijzen wij je naar betreffende derde partij. Deze derde partij moet jou ook voorzien van toegang tot deze consent flow. In de praktijk is dit via een knop op hun website of via een link in een mailtje. Uiteraard hebben we voor partijen die reeds op onze Koppelingen pagina staan in Loket een knop beschikbaar waarbij de gebruiker direct wordt doorgeleid naar de consent flow (of op zijn minst een formulier waarna de derde partij de consent flow beschikbaar stelt).

De stappen:

1. De derde partij leidt jou naar de consent pagina. Dit is dikwijls vanuit een link of een knop.

2. Je komt terecht op de consent pagina van Loket.

3. Je vult je inloggegevens in. Dus gebruikersnaam + wachtwoord van de Loket gebruiker waarmee je de flow wil doorlopen. Dit is dus niet altijd de gebruiker waarmee je zelf bent ingelogd in Loket.

4. Vervolgens zie je tot welke gegevens de applicatie toegang vraagt.

5. Druk op Toestaan. Je wordt teruggeleid naar de andere applicatie.

Je hebt nu de consent flow doorlopen en de koppeling gelegd. De verdere verwerking (en eventuele aanvullende acties) verschilt per applicatie.

api@loket.nl

api@loket.nl is het adres voor alle API koppeling gerelateerde vragen.

Wat zijn activities/endpoints

Je ziet ze soms voorbij komen, de termen activities ofwel endpoints. Dit is developer taal voor gegevensgroepen, bijvoorbeeld; dienstverbanden, loonruns en arbeidstijd. Technisch gezien is Loket opgeknipt in kleine stukjes zodat men gebruikers rechten kan geven waarmee ze enkel gedeeltes van een werkgever in kunnen zien. Aan de achterkant werkt dit niet anders. Elke koppeling heeft toegang tot een bepaald aantal endpoints welke bepalend zijn voor de gegevens die over de lijn gaan. Met andere woorden, ook al geef je een Loket gebruiker alle rechten dan nog kan er enkel de informatie over de lijn gaan waarvoor de endpoints zijn vrijgegeven. Maar uiteraard raden we altijd aan om enkel de rechten vrij te geven die minimaal noodzakelijk zijn.

Developer portal

Technische documentatie met betrekking tot onze developer portal is beschikbaar op ons developer portal https://developer.loket.nl .

Hier kan men alle informatie vinden over het gebruik van onze API. Je moet dan denken aan hoe de autorisatie (consent flow) technisch gezien werkt. Een introductie in de Loket API. De veel gestelde vragen en uitleg van foutmeldingen maar uiteraard ook alle endpoints en welke gegevens daar allemaal onder vallen.