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, systeem-aan-systeem, zaken kan doen met de omgeving van een burger. De burger houdt daarbij zelf de regie.

Het verkeer gaat twee kanten op, in twee soorten:

Soort verkeer	Heen	Terug
Gegevens	De organisatie stuurt een vraag: welke gegevens heeft zij nodig, en waarvoor	Bij akkoord van de burger komen de gevraagde gegevens terug, geverifieerd en ondertekend, en niets meer dan dat
Berichten	De organisatie bezorgt een bericht bij de burger	De burger stuurt een bericht aan de organisatie

Het gegevens-deel kunt u op deze pagina direct proberen. Het berichten-deel is in aanbouw, zie Berichten.

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

Zo werkt het

U stelt een vraag. In de vraag staat precies welke gegevens u nodig heeft, bijvoorbeeld alleen "is er gezag over dit kind" uit de ouderschapsverklaring. De vraagtaal heet DCQL en komt uit de Europese wallet-standaard OpenID4VP 1.0.
De burger geeft akkoord. De omgeving van de burger toont wie wat vraagt en waarvoor. In deze proefomgeving gebeurt dat akkoord automatisch namens de verzonnen burger.
U krijgt ondertekende gegevens terug. Alleen de gevraagde velden, afkomstig uit verklaringen die door de uitgevende organisatie digitaal zijn ondertekend (het Europese SD-JWT VC-formaat), plus een handtekening van de burger die uw eigen controlegetal insluit. U kunt alles zelf wiskundig controleren, zie Een antwoord controleren.

Zelf proberen

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 vindt u per vraag een ondertekende presentatie terug onder vp_token. Velden die u niet vroeg, blijven dicht.

Endpoints

Endpoint	Wat het doet
`GET /.well-known/burger-api`	Metadata: welke verklaringen beschikbaar zijn, met welke velden, en waar de endpoints staan.
`GET /openapi.json`	De OpenAPI-beschrijving van dit koppelvlak, voor in uw eigen tooling.
`POST /sandbox/vraag`	Een gegevens-vraag stellen (DCQL). Antwoord: per vraag-id de ondertekende presentaties.
`POST /verifieer`	Een presentatie laten nakijken, als demonstratie. In productie controleert u zelf.
`GET /vertrouwenslijst`	Welke uitgevers deze proefomgeving vertrouwt, met hun publieke sleutels.
`GET /.well-known/jwt-vc-issuer/uitgevers/{id}`	De publieke sleutels per uitgever, op de plek waar de SD-JWT-VC-standaard ze voorschrijft.

Beschikbare gegevens

De verzonnen 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.

Verklaring (vct)	Inhoud	Uitgever in deze proefomgeving
`urn:eudi:pid:1`	Identiteit, met het BSN	rvig
`urn:nl.pubcommons:kind-ouder-gezag:1`	Kind-ouder-relatie en gezag	gemeente-utrecht
`urn:nl.pubcommons:arbeidsstatus:1`	Of en hoe de ouder werkt of studeert (de arbeidseis)	uwv
`urn:nl.pubcommons:kinderopvangcontract:1`	Het opvangcontract: locatie, uren, uurtarief	kinderopvang-de-vlinder
`urn:nl.pubcommons:detentiestatus:1`	Detentiestatus, bewust kort geldig	justid

Een antwoord controleren

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

Lees in het credential 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.
Controleer of die uitgever op de vertrouwenslijst staat.
Controleer de handtekening van de uitgever en de geldigheid, en of elk onthuld veld cryptografisch bij het credential hoort.
Controleer de handtekening van de burger: daar moeten uw eigen controlegetal (nonce) en uw client_id in staan, zodat niemand een oud antwoord kan hergebruiken.

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

Wat is echt, wat is namaak

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

Onderdeel	Echt of namaak
De handtekeningen (ES256), het per-veld delen (selective disclosure) en de koppeling aan uw controlegetal	Echt, volgens de Europese standaarden en daartegen nagemeten
De vraagtaal DCQL	Echt, als deelverzameling (vragen op veld-niveau)
De burger, de gegevens en de uitgevers (rvig, gemeente-utrecht, uwv, justid, kinderopvang-de-vlinder)	Verzonnen; de echte organisaties zijn hier niet bij betrokken en er zijn geen echte persoonsgegevens
Het akkoord van de burger	In deze proefomgeving automatisch; in het echte product beslist de burger per verzoek
Toegangs- en registratiecertificaten van de vragende organisatie, statuslijsten voor intrekking, de volledige OpenID4VP-berichtenstroom	Volgen in de volgende versie

Berichten

Naast gegevens vragen komt er een berichten-deel: organisaties kunnen een bericht bij de burger bezorgen (vergelijkbaar met de Berichtenbox, maar dan bij de burger zelf) en de burger kan berichten aan organisaties sturen. Dit deel is in aanbouw en krijgt een eigen endpoint naast het gegevens-deel, met dezelfde manier van ondertekenen en vertrouwen.

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.