Burger-API

Iedere burger een eigen digitale omgeving, met een eigen aansluitpunt voor de overheid. Dat is de Burger-API: de plek waar een organisatie rechtstreeks zaken kan doen met de omgeving van een burger, terwijl de burger zelf de regie houdt.

Het verkeer gaat twee kanten op, in drie soorten:

Het bewijzen-deel werkt en kun je op deze pagina direct proberen. Berichten, signalen en taken zijn in aanbouw.

Deze omgeving is een proefomgeving: een fictieve burger (Maria de Vries) antwoordt automatisch, zodat je het mechanisme kunt ervaren zonder echte burger en zonder echte persoonsgegevens. In het echte product beslist de burger zelf over elke gegevensdeling.

Moderne open standaarden

De Burger-API is gebouwd op open Europese standaarden: dezelfde bouwstenen als het European Digital Identity Wallet en het European Business Wallet. De vraag gaat in de vraagtaal DCQL uit OpenID4VP 1.0, de bewijzen zijn in het Europese SD-JWT VC-formaat met ES256-handtekeningen, en de sleutels van uitgevers staan op de plekken waar die standaarden ze voorschrijven. Voor het berichten-deel sluit de Burger-API aan op de richting van het Federatief Berichtenstelsel van de Nederlandse overheid, en de gedachte dat gegevens bij de bron blijven, hier bij de burger zelf, past in de lijn van het Federatief Datastelsel. Er zijn geen eigen bedachte formaten: wat hier over de lijn gaat, kun je met standaard-tooling lezen en controleren.

Zo werkt het

1. Je stelt als organisatie een vraag. In de vraag staat precies welke bewijzen je nodig hebt, bijvoorbeeld alleen "is er gezag over dit kind" uit de ouderschapsverklaring.
2. De burger geeft akkoord. De omgeving van de burger toont wie wat vraagt en waarvoor. In deze proefomgeving gebeurt dat akkoord automatisch namens de fictieve burger.
3. Je krijgt ondertekende bewijzen terug. Alleen de gevraagde velden, afkomstig uit verklaringen die door de uitgevende organisatie digitaal zijn ondertekend, plus een handtekening van de burger die jouw eigen controlegetal insluit. Alles is wiskundig na te rekenen.

Zelf proberen

Liever eerst kijken? Op de kinderopvang-demo zie je de volledige conforme rondgang live gebeuren: het venster van de vragende organisatie en dat van de burger naast elkaar. Jij klikt zelf, namens de fictieve burger, op Akkoord.

Zelf aan de slag kan direct vanuit je browser op de probeer-pagina: elk endpoint met een aanpasbaar voorbeeld en een verstuur-knop. Of met curl, Postman of een eigen programma: de machine-leesbare beschrijving staat op /openapi.json (direct te importeren in Postman) en een kant-en-klaar voorbeeldverzoek op /sandbox/voorbeeld.

curl -X POST https://burgerapi.pub.nl/sandbox/vraag \
  -H "content-type: application/json" \
  -d '{
    "client_id": "mijn-organisatie",
    "nonce": "mijn-controlegetal",
    "dcql_query": { "credentials": [ {
      "id": "ouderschap",
      "format": "dc+sd-jwt",
      "meta": { "vct_values": ["urn:nl.pubcommons:kind-ouder-gezag:1"] },
      "claims": [ { "path": ["kind"] }, { "path": ["gezag"] } ]
    } ] }
  }'

In het antwoord vind je per vraag een ondertekende presentatie terug onder vp_token. Velden die je niet vroeg, blijven dicht.

De conforme route

Naast de snelle proef-route hierboven is er de conforme route: de volledige berichtenstroom zoals de Europese standaarden hem voorschrijven, met echte controles op wie er vraagt en wat die mag vragen.

1. Registreer je als vrager via POST /sandbox/vrager-registratie. De sandbox-registrar geeft je in één keer een testsleutel, een toegangscertificaat (wie ben je) en een registratiecertificaat (wat mag je vragen, voor welk doel). In het echt doe je dit één keer bij een nationale registrar; hier is het één aanroep.
2. Zet een ondertekend verzoek-object klaar op een eigen URL: een JWT met je certificaatketen erin, je vraag (DCQL), een vers controlegetal, het registratiecertificaat en een publieke sleutel waarnaar het antwoord versleuteld moet worden.
3. Nodig de omgeving uit via POST /conform/uitnodiging met je request_uri. De omgeving controleert je certificaatketen, je handtekening, en of je vraag binnen je registratie blijft; wie meer vraagt dan geregistreerd wordt geweigerd met uitleg.
4. Ontvang het antwoord versleuteld op je eigen response_uri (direct_post.jwt) en controleer het zelf.

Een compleet werkend voorbeeld van deze hele rondgang staat in de broncode: voorbeeld-client/dienst-toeslagen-conform.mjs. Let op: de omgeving moet jouw request- en response-URL kunnen bereiken; lokaal werkt dat vanzelf, tegen de live sandbox moet je zelf publiek bereikbaar zijn.

Conformiteitstesten

De conforme route is doorgemeten met de conformance-testsuite van de OpenID Foundation: dezelfde testen waarmee echte wallets zich laten certificeren.

Dit is een testuitslag, geen officiële certificering door de OpenID Foundation.

Endpoints

Beschikbare bewijzen

De fictieve burger heeft vijf verklaringen, gekozen rond één echte casus: de nieuwe financiering van de kinderopvang die per 2029 is voorzien. Alles wat de uitvoerder daarvoor wil weten, kan de burger hier zelf aanleveren.

Een antwoord controleren

Je hoeft deze proefomgeving niet op haar woord te geloven: elk antwoord is wiskundig na te rekenen. Dat gaat in vier stappen:

1. Lees in het bewijs wie de uitgever is (de iss-URL) en haal diens publieke sleutels op via het vaste pad /.well-known/jwt-vc-issuer, zoals de SD-JWT-VC-standaard voorschrijft.
2. Controleer of die uitgever op de vertrouwenslijst staat.
3. Controleer de handtekening van de uitgever en de geldigheid, en of elk onthuld veld cryptografisch bij het bewijs hoort.
4. Controleer de handtekening van de burger: daar moeten jouw eigen controlegetal (nonce) en jouw client_id in staan, zodat niemand een oud antwoord kan hergebruiken.

Wie het snel wil zien: stuur een presentatie naar POST /verifieer en je krijgt de uitslag met de onthulde velden terug.

Wat is echt, wat is namaak

Deze proefomgeving gebruikt echte techniek met fictieve inhoud. Zodat er geen misverstand ontstaat:

Berichten en signalen

Naast bewijzen vragen komen er twee verkeer-soorten bij. Berichten: organisaties bezorgen een bericht bij de burger (vergelijkbaar met de Berichtenbox, maar dan bij de burger zelf) en de burger stuurt berichten terug. Signalen en taken: korte gestructureerde seintjes over een lopende zaak, zoals "de aanvraag is ontvangen", "vul formulier X aan" of, vanuit de burger, "ik wil aanvragen". Beide lopen straks over een eigen endpoint naast het bewijzen-deel, met dezelfde manier van ondertekenen en vertrouwen: elk bericht en elk taakje draagt een zegel van de afzender, en een link in een taakje is alleen klikbaar als hij naar het geregistreerde domein van die afzender wijst.

Dit sluit aan op de Nederlandse wet over elektronisch berichtenverkeer met de overheid (de Wet modernisering elektronisch bestuurlijk verkeer). Die wet hangt formele elektronische bezorging niet aan één landelijke voorziening op, maar aan "een systeem voor gegevensverwerking waarin de geadresseerde toegang heeft tot het bericht", in combinatie met de uitdrukkelijke keuze van de burger voor dat kanaal en een notificatie-seintje binnen 48 uur (artikel 2:10 en 2:8 van de Algemene wet bestuursrecht). Het berichten-deel wordt zo ontworpen dat het die eisen kan dragen: instemming per afzender, het notificatie-seintje, en een ontvangst-log als bewijs.

De Burger-API is een initiatief van PUB. Dit is een demonstratie-omgeving; er worden geen echte persoonsgegevens verwerkt. Vragen of meedoen: via pub.nl.