Consent API
- Koen Voermans
Titel | Consent API |
Status | In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer |
Versie | Documentatie: 0.9.1 |
schemaVersion: 0.9.1 | |
Datum | 27 September 2024 |
Auteur | Architectenraad Edu-V |
Acties |
|
De Consent API wordt gebruikt door leveranciers die gegevens uit gaan wisselen waarvoor toestemming vereist is vanuit de onderwijsorganisatie. De onderwijsorganisatie heeft regie op gegevens en bepaalt welke gegevensdiensten er uitgewisseld worden tussen referentiecomponenten. Meer informatie hierover is terug te vinden in de sectie Regie op gegevens.
De technische specificatie bestaat uit:
Samenvatting
Gegevensdienst | Consent |
Scopes | eduv.consent |
Objecten | |
Bron, Afnemer, Verzender, Ontvanger | Consentmanagement |
Afnemer | Consentdashboard |
Endpoints | Consent API Bron GET ConsentStatuses GET ConsentStatuses by School PUT a ConsentRevoke to Data Provider or Data Consumer PUT a ConsentRequest to Data Provider Consent API Afnemer GET ConsentStatuses GET ConsentStatuses by School PUT a ConsentRevoke to Data Provider or Data Consumer PUT a ConsentNotification to Data Consumer Consent API Verzender GET ConsentStatuses GET ConsentStatuses by School PUT a ConsentRevoke to Data Provider or Data Consumer PUT a ConsentConfirmation to Data Provider PUT a ConsentRequest to Data Provider Consent API Ontvanger GET ConsentStatuses GET ConsentStatuses by School PUT a ConsentRevoke to Data Provider or Data Consumer PUT a ConsentNotification to Data Consumer GET ConsentConfirmations from Data Consumer after a specified timestamp GET ConsentRequests from Data Consumer after a Specfied timestamp |
De Consent API wordt afhankelijk van de gekozen implementatievariant geïmplementeerd door Bron, Ontvanger en optioneel ook door Afnemer en Verzender. De Consent API is geïntegreerd in de referentiecomponent Consentmanagement. De referentiecomponent Consentdashboard kan optioneel informatie uit de Consent API verzamelen en vervolgens tonen in een dashboard aan een onderwijsmedewerker van de onderwijsorganisatie.
In alle objecten is een referentie opgenomen naar de Data Provider of de Data Consumer. De Data Provider is de leverancier waarbij de data is ontstaan. Dit betreft leveranciers in de transactierollen van Bron of Verzender. De Data Consumer is de leverancier die de data opvraagt of ontvangt. Dit betreft leveranciers in de transactierollen van Afnemer of Ontvanger.
Een Consent wordt geregistreerd op het niveau van een onderwijsaanbieder. Indien er in de referentiecomponent Consentmanagement toestemming is verleend op een hoger niveau in de organisatie van de school (bijvoorbeeld het volledige onderwijsbestuur) dan wordt er voor alle onderliggende onderwijsaanbieders een consent geregistreerd.
Object: ConsentStatus
Dit object geeft de status weer van een consent zoals deze is geregistreerd bij de Bron, Afnemer, Verzender of Ontvanger.
Veld | Type | Format | Omschrijving | Voorbeeld | O/V | Vullingsregel |
provider | string | uuid | Unieke identifier gegenereerd door de Data Provider van de gegevensdienst waarop de registratie van consent van toepassing is. | - | V | De Data Provider is de Bron of Verzender waarvoor een activering is gedaan. Voor de SIS API is dat bijvoorbeeld de leverancier met de referentiecomponent Administratiesysteem onderwijsdeelnemer. |
consumer | string | uuid | Unieke identifier gegenereerd door de Data Consumer van de gegevensdienst waarop de registratie van consent van toepassing is. | - | O | De Data Consumer is de Afnemer of Ontvanger. Voor de SIS API is dat bijvoorbeeld de leverancier met de referentiecomponent Aanspraakmanager, Gebruiksomgeving digitaal leermateriaal of Digitaal toetssysteem. Veld is leeg zodra de Data Provider geen ConsentConfirmation heeft vanuit de Data Consumer. |
school | object | schoolreference | Referentie naar de identifier van de onderwijsaanbieder waarvoor consent is geregistreerd. | V | Â | |
api | string | ENUM | De API waarop de registratie van het consent van toepassing is. |
| V | Betreft een API uit het Ecosysteem waarvoor activering een vereiste is voor uitwisseling. |
scopes | array | ENUM | De scope van de gegevensdienst waarop de registratie van het consent van toepassing is. |
| V | Betreft één of meerdere scopes van de api. |
provider | string | ENUM | De status van van het consent bij de Data Provider |
| V | In lijn met de beschrijving bij providerReferenceId betreft het de status van de instemming bij de Bron of Verzender waarvoor al dan niet instemming is verleend. |
consumer | string | ENUM | De status van het consent bij de Data Consumer |
| O | In lijn met de beschrijving bij consumerReferenceId betreft het de status van de instemming bij de Afnemer of Ontvanger waarvoor al dan niet instemming is verleend. Veld is leeg zodra de Data Provider geen ConsentConfirmation heeft vanuit de Data Consumer. |
Object: ConsentRevoke
Dit bericht kan door de Bron, Afnemer, Verzender en Ontvanger worden gestuurd om een consent in te trekken.
Veld | Type | Format | Omschrijving | Voorbeeld | O/V | Vullingsregel |
provider | string | uuid | Unieke identifier gegenereerd door de Data Provider van de gegevensdienst waarop de registratie van consent van toepassing is. | - | V | De Data Provider is de Bron of Verzender waarvoor een activering is gedaan. Voor de SIS API is dat bijvoorbeeld de leverancier met de referentiecomponent Administratiesysteem onderwijsdeelnemer. |
consumer | string | uuid | Unieke identifier gegenereerd door de Data Consumer van de gegevensdienst waarop de registratie van consent van toepassing is. | - | O | De Data Consumer is de Afnemer of Ontvanger. Voor de SIS API is dat bijvoorbeeld de leverancier met de referentiecomponent Aanspraakmanager, Gebruiksomgeving digitaal leermateriaal of Digitaal toetssysteem. |
school | object | schoolreference | Referentie naar de identifier van de onderwijsaanbieder waarvoor consent is geregistreerd. | V | Â | |
api | string | ENUM | De API waarop de registratie van het consent van toepassing is. |
| V | Betreft een API uit het Ecosysteem waarvoor activering een vereiste is voor uitwisseling. |
scopes | array | ENUM | De scope van de gegevensdienst waarop de registratie van het consent van toepassing is. |
| V | Betreft één of meerdere scopes van de api. |
provider | string | ENUM | De status van van het consent bij de Data Provider |
| V* | In lijn met de beschrijving bij providerReferenceId betreft het de status van de instemming bij de Bron of Verzender waarvoor al dan niet instemming is ingetrokken. Veld is gevuld indien het consent is ingetrokken aan de zijde van de Bron of Verzender. |
consumer | string | ENUM | De status van het consent bij de Data Consumer |
| V* | In lijn met de beschrijving bij consumerReferenceId betreft het de status van de instemming bij de Afnemer of Ontvanger waarvoor al dan niet instemming is ingetrokken. Veld is gevuld indien het consent is ingetrokken aan de zijde van de Afnemer of Ontvanger. |
Object: ConsentNotification
Dit object kan door een Bron of Verzender naar respectievelijk een Afnemer of Ontvanger worden gestuurd als melding van een nieuw consent dat is verleend.
Veld | Type | Format | Omschrijving | Voorbeeld | O/V | Vullingsregel |
provider | string | uuid | Unieke identifier gegenereerd door de Data Provider van de gegevensdienst waarop de registratie van consent van toepassing is. | - | V | De Data Provider is de Bron of Verzender waarvoor een activering is gedaan. Voor de SIS API is dat bijvoorbeeld de leverancier met de referentiecomponent Administratiesysteem onderwijsdeelnemer. |
consumer | string | uuid | Unieke identifier gegenereerd door de Data Consumer van de gegevensdienst waarop de registratie van consent van toepassing is. | - | O | De Data Consumer is de Afnemer of Ontvanger. Voor de SIS API is dat bijvoorbeeld de leverancier met de referentiecomponent Aanspraakmanager, Gebruiksomgeving digitaal leermateriaal of Digitaal toetssysteem. Veld is gevuld zodra deze ConsentNotification volgt na een ConsentRequest vanuit de Data Consumer. |
school | object | schoolreference | Referentie naar de identifier van de onderwijsaanbieder waarvoor consent is geregistreerd. | V | Â | |
api | string | ENUM | De API waarop de registratie van het consent van toepassing is. |
| V | Betreft een API uit het Ecosysteem waarvoor activering een vereiste is voor uitwisseling. |
scopes | array | ENUM | De scope van de gegevensdienst waarop de registratie van het consent van toepassing is. |
| V | Betreft één of meerdere scopes van de api. |
providerStatus | string | ENUM | De status van het consent bij de Data Provider |
| V | Indien er een nieuw consent is geregistreerd dan is de status accepted. Indien een ConsentRequest wordt afgewezen dan is de status declined. Indien een ConsentRequest nog bevestigd dient te worden dan is de status pending. |
Object: ConsentConfirmation
Dit bericht kan door een Ontvanger worden gedeeld met een Verzender om te terug te melden dat een consent is bevestigd.
Veld | Type | Format | Omschrijving | Voorbeeld | O/V | Vullingsregel |
provider | string | uuid | Unieke identifier gegenereerd door de Data Provider van de gegevensdienst waarop de registratie van consent van toepassing is. | - | V | De Data Provider is de Bron of Verzender waarvoor een activering is gedaan. Voor de SIS API is dat bijvoorbeeld de leverancier met de referentiecomponent Administratiesysteem onderwijsdeelnemer. |
consumer | string | uuid | Unieke identifier gegenereerd door de Data Consumer van de gegevensdienst waarop de registratie van consent van toepassing is. | - | V | De Data Consumer is de Afnemer of Ontvanger. Voor de SIS API is dat bijvoorbeeld de leverancier met de referentiecomponent Aanspraakmanager, Gebruiksomgeving digitaal leermateriaal of Digitaal toetssysteem. |
school | object | schoolreference | Referentie naar de identifier van de onderwijsaanbieder waarvoor consent wordt bevestigd. | V | Â | |
api | string | ENUM | De API waarop de registratie van het consent van toepassing is. |
| V | Betreft een API uit het Ecosysteem waarvoor activering een vereiste is voor uitwisseling. |
scopes | array | ENUM | De scope van de gegevensdienst waarop de registratie van het consent van toepassing is. |
| V | Betreft één of meerdere scopes van de api. |
consumerStatus | string | ENUM | De status van het consent bij de Data Consumer |
| V | De Ontvanger geeft aan of het Consent bevestigd is. Ontvanger kan als antwoord op een ConsentNotification of een nieuwe ConsentStatus direct een ConsentConfirmation met de status accepted of declined terugmelden. Als alternatief kan de Ontvanger ook een ConsentConfirmation met pending terugsturen. Deze optie kan bijvoorbeeld gebruikt worden om eerst bij de Applicatiebeheerder aan de zijde van de Ontvanger een bevestiging te vragen op het activeren van de gegevensuitwisseling. |
Object: ConsentRequest
Dit object kan door een Afnemer of Ontvanger worden gedeeld met een Bron of Verzender als verzoek om een consent te verlenen.
Veld | Type | Format | Omschrijving | Voorbeeld | O/V | Vullingsregel |
consumer | string | uuid | Unieke identifier gegenereerd door de Data Consumer van de gegevensdienst waarop de registratie van consent van toepassing is. | - | V | De Data Consumer is de Afnemer of Ontvanger. Voor de SIS API is dat bijvoorbeeld de leverancier met de referentiecomponent Aanspraakmanager, Gebruiksomgeving digitaal leermateriaal of Digitaal toetssysteem. |
school | object | schoolreference | Referentie naar de identifier van de onderwijsaanbieder waarvoor consent wordt gevraagd. | V | Â | |
api | string | ENUM | De API waarop de registratie van het consent van toepassing is. |
| V | Betreft een API uit het Ecosysteem waarvoor activering een vereiste is voor uitwisseling. |
scopes | array | ENUM | De scope van de gegevensdienst waarop de registratie van het consent van toepassing is. |
| V | Betreft één of meerdere scopes van de api. |
consumerStatus | string | ENUM | De status van het consent bij de Data Consumer |
| V | De Afnemer of Ontvanger geeft middels de status |
Status- en foutcodes
Voor alle APIs uit het Afsprakenstelsel Edu-V zijn de status- en foutcodes beschreven op de pagina Status- en foutcodes. Hierbij is onderscheid gemaakt in algemene en voor de API specifieke status- en foutcodes.
Technisch: API specificatie
Release notes
0.0.1: Eerste draft van de API.
0.0.2: Objecten en YAML files zijn toegevoegd t.b.v. de 80 procent specificatie van de POC’s.
0.0.3: De technische specificatie is verder uitgewerkt.
edu_org_id is toegevoegd aan alle endpoints als implementatie van regie op gegevens en de M2M identificatie en authenticatie.
scopes zijn toegevoegd aan het object consent. Het is daarmee mogelijk om een consent te registreren voor een specifiek informatieobject uit een gegevensdienst.
De status- en foutcodes zijn toegevoegd aan de documentatie en aan de YAML.
In de YAML is aangegeven welke referentiecomponent de endpoints aanbiedt als Producer.
De YAML is geactualiseerd op basis van de bovenstaande wijzigingen.
0.0.4: De herziening consent zoals uitgewerkt in Regie op gegevens heeft geleid tot een nieuwe API uitwerking. In deze API uitwerking is rekening gehouden met de verschillende implementatievarianten:
0.0.5: De pagina is besproken tijdens de bijeenkomst van de Architectenraad Edu-V en is gereed voor de ROSA-architectuurscan.
0.0.6: Typo’s verwijderd uit de YAML file. Query parameter since toegevoegd aan endpoint consentstatuses.
0.0.7: APIs en scopes zijn bijgewerkt in de Objecten.
0.0.8: Toelichting proderReferenceId en consumerReferenceId verduidelijkt.
0.0.9: De volgende wijzigingen zijn gedaan:
Wijzigingen in de architectuur:
Attribuut schemaVersion is verwijderd uit de objecten.
Query parameter schemaVersion is verwijderd uit de koppelvlakken.
Query parameter edu_org_id is verwijderd uit de koppelvlakken waar consent voor nodig is.
Query parameters orgMasterId, orgId en orgIdType zijn toegevoegd om informatie over een onderwijsaanbieder op te vragen.
Wijzigingen in de documentatie en de YAML:
Het attribuut edu_org_id is vervangen door een verwijzing naar een onderwijsaanbieder.
De verplichte en optionele attributen zijn bijgewerkt. Een consentstatus kan nu ook eenzijdig gedeeld worden vanuit de Data provider zonder informatie te delen over de Data Consumer.
/ achter endpoints verwijderd.
0.9.0: Het Architectuurkader Edu-V is vastgesteld als startpunt voor de implementatie. Tevens is instemming verleend op verdere doorontwikkeling van het Architectuurkader Edu-V op basis van de Architectuurprincipes. Dit akkoord is verleend op het Bestuurlijk Overleg van 27 mei 2024.
De afspraken m.b.t. Regie op gegevens wordt tijdens de eerste release geïmplementeerd. Na een succesvolle implementatie wordt de uiteindelijke 1.0.0 versie vastgesteld.
0.9.1: De volgende wijzigingen zijn gedaan:
Op basis van RFC002 is de scope aangepast met een prefix
eduv.. Dit stelt leveranciers in staat om onderscheid te maken tussen gegevensuitwisselingen met leveranciers binnen en buiten het Edu-V afsprakenstelsel.De Vestigingserkenning is als secundaire identifier voor een onderwijsaanbieder verwijderd uit de koppelvlakspecificatie.