Consent API

Titel

Consent API

Status

In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer

Versie

Documentatie: 0.0.9

schemaVersion: 0.0.7

Datum

24 April 2024

Auteur

Architectenraad Edu-V

Acties

  • Geen openstaande 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

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
ReferenceId

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
ReferenceId

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.

Zie referentie naar school

V

 

api

string

ENUM

De API waarop de registratie van het consent van toepassing is.

students-api
employees-api
education-api
association-api
delivery-api
entitlement-api
usage-api
progress-api
results-api

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.

student.basic
student.communication
student.demographics
student.accessibility
student.deliveryaddress
employee.basic
employee.communication
employee.roles
education
association
delivery.portal
delivery.dashboard
entitlement.portal
entitlement.dashboard
usage.dashboard
progress
result

V

Betreft één of meerdere scopes van de api.

provider
Status

string

ENUM

De status van van het consent bij de Data Provider

accepted
declined
revoked
pending

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
Status

string

ENUM

De status van het consent bij de Data Consumer

accepted
declined
revoked
pending

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
ReferenceId

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
ReferenceId

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.

Zie referentie naar school

V

 

api

string

ENUM

De API waarop de registratie van het consent van toepassing is.

students-api
employees-api
education-api
association-api
delivery-api
entitlement-api
usage-api
progress-api
results-api

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.

student.basic
student.communication
student.demographics
student.accessibility
student.deliveryaddress
employee.basic
employee.communication
employee.roles
education
association
delivery.portal
delivery.dashboard
entitlement.portal
entitlement.dashboard
usage.dashboard
progress
result

V

Betreft één of meerdere scopes van de api.

provider
Status

string

ENUM

De status van van het consent bij de Data Provider

revoked

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
Status

string

ENUM

De status van het consent bij de Data Consumer

revoked

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
ReferenceId

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
ReferenceId

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.

Zie referentie naar school

V

 

api

string

ENUM

De API waarop de registratie van het consent van toepassing is.

students-api
employees-api
education-api
association-api
delivery-api
entitlement-api
usage-api
progress-api
results-api

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.

student.basic
student.communication
student.demographics
student.accessibility
student.deliveryaddress
employee.basic
employee.communication
employee.roles
education
association
delivery.portal
delivery.dashboard
entitlement.portal
entitlement.dashboard
usage.dashboard
progress
result

V

Betreft één of meerdere scopes van de api.

providerStatus

string

ENUM

De status van het consent bij de Data Provider

pending
accepted
declined

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
ReferenceId

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
ReferenceId

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.

Zie referentie naar school

V

 

api

string

ENUM

De API waarop de registratie van het consent van toepassing is.

delivery-api
entitlement-api
usage-api
progress-api
results-api

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.

delivery.portal
delivery.dashboard
entitlement.portal
entitlement.dashboard
usage.dashboard
progress
result

V

Betreft één of meerdere scopes van de api.

consumerStatus

string

ENUM

De status van het consent bij de Data Consumer

pending
accepted
declined

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
ReferenceId

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.

Zie referentie naar school

V

 

api

string

ENUM

De API waarop de registratie van het consent van toepassing is.

students-api
employees-api
education-api
association-api
delivery-api
entitlement-api
usage-api
progress-api
results-api

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.

student.basic
student.communication
student.demographics
student.accessibility
student.deliveryaddress
employee.basic
employee.communication
employee.roles
education
association
delivery.portal
delivery.dashboard
entitlement.portal
entitlement.dashboard
usage.dashboard
progress
result

V

Betreft één of meerdere scopes van de api.

consumerStatus

string

ENUM

De status van het consent bij de Data Consumer

accepted

V

De Afnemer of Ontvanger geeft middels de status accepted aan dat er een consentverzoek is geregistreerd.

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.