Overzicht & scope

OKD (Open Koppelingen Document Management) is een onderwijsstandaard voor documentuitwisseling, gebaseerd op OOAPI v5. In tegenstelling tot de Eduarte-specifieke (E-)koppelingen volgt OKD de landelijke OOAPI/OKD-conventies (Engelstalig). De gezaghebbende definitie staat extern:

Officiële standaard: https://github.com/Onderwijs-Koppelingen-OKx/OKD-Document-Management

Deze specificatie beschrijft OKD zoals geïmplementeerd in Eduarte Connect (een subset) en verwijst voor de volledige definitie, schema’s en conventies naar de officiële standaard.

• Standaard: OOAPI v5 / OKD
• Volledige OpenAPI-specificatie: meegeleverd als OKD_v1.0.yml.
• Interactieve referentie online: API-referentie van OKD
• Paden: volgens OOAPI (bijv. /persons, /associations, /documents); de exacte base-URL staat in de meegeleverde OKD_v1.0.yml.

Rol van Eduarte: bron- en registratiepartij — Eduarte levert de onderwijscontext (personen, associations, offerings) en registreert DMS-documenten gekoppeld aan een deelnemer of verbintenis.

Status — gedeeltelijk beschikbaar. Het koppelen van documenten aan de OKD-categorieën (enrollment / bpv / graduation / examination) vereist een toekomstige MORA-component en is nog niet volledig beschikbaar.

Aan de slag & dev-omgeving

1. Toegang aanvragen — vraag via Eduarte (connect@eduarte.nl) OAuth2-clientgegevens aan.
2. Scopes — OKD kent de scopes okd:alldocuments (alle documenten) en okd:examdocuments (examendocumenten). Vraag de scope(s) aan die je nodig hebt.
3. Token ophalen — haal een access-token op via de OAuth2 Client Credentials-flow.
4. Aanroepen — stuur het token mee als Authorization: Bearer <token> en roep de OOAPI-endpoints aan (zie Endpoints op hoofdlijnen).
5. Testen — gebruik de beschikbare ontwikkel-/testomgeving voordat je in productie gaat.

Beveiliging

Alle Connect API’s worden uniform beveiligd. De maatregelen hieronder gelden voor elke connector; afwijkingen staan in de connector-specifieke secties.

Transport (TLS)

Alle communicatie verloopt verplicht via HTTPS. Minimaal TLS 1.2, bij voorkeur TLS 1.3. Er zijn geen HTTP-endpoints, ook niet voor redirects. Een geldig servercertificaat is vereist. Hierin volgen we de aanbeving van de NSCT

Authenticatie & autorisatie

Authenticatie verloopt via OAuth 2.0 met de Client Credentials-flow (server-to-server):

• Token-endpoint: https://login.educus.nl/oauth2/token?organisatieuuid=<uuid>
• De client wisselt zijn client_id en client_secret in voor een access-token.
• Het verkregen token wordt bij elke aanroep meegestuurd in de Authorization: Bearer <token>-header.

Scopes bepalen de toegangsrechten volgens het principe van least privilege. Elke API kent één of meer scopes; een token bevat alleen de scopes die de client nodig heeft. De vereiste scope(s) per connector staan in de connector-specifieke sectie.

Waar OAuth 2.0 niet mogelijk is (bijvoorbeeld bij legacy-integraties), kan als terugvaloptie een Bearer-token (JWT) worden gebruikt.

Per endpoint

Elk endpoint heeft een expliciete security-definitie. Onjuiste of ontbrekende autorisatie leidt tot een 401 Unauthorized (niet geauthenticeerd) of 403 Forbidden (onvoldoende rechten); zie Foutafhandeling.

Conventies (OOAPI v5)

OKD volgt de OOAPI v5-conventies, die afwijken van de Connect-conventies van de E-koppelingen:

• Engelstalige resources en velden.
• Paginering, filtering, sortering en het uitbreiden van objecten (expand) volgens OOAPI.
• OOAPI-objectmodel: het overkoepelende concept educations komt niet als endpoint voor; programOffering, courseOffering en conceptOffering lopen via het offering-endpoint, en de associatietypen via het association-endpoint.

Raadpleeg de officiële standaard en de meegeleverde OKD_v1.0.yml voor de exacte conventies, parameters en schema’s.

Foutafhandeling

OKD volgt de foutafhandeling van de OOAPI/OKD-standaard (niet het Connect-foutmodel van de E-koppelingen). Zie de officiële specificatie voor de foutstructuur en statuscodes.

Throttling & rate limiting

Alle endpoints kennen rate limiting om misbruik en overbelasting te voorkomen. Dit wordt op infrastructuurniveau afgedwongen via de Topicus API-gateway.

Bij overschrijding van de limiet antwoordt de API met 429 Too Many Requests. De response kan de volgende headers bevatten:

Aanbevolen client-gedrag

• Respecteer Retry-After en wacht ten minste het opgegeven aantal seconden.
• Gebruik exponential backoff met jitter bij herhaalde 429-responses.
• Verspreid bulk-aanroepen over de tijd in plaats van ze gelijktijdig te versturen.

Endpoints op hoofdlijnen

Zoals geïmplementeerd in Eduarte Connect. Voor de volledige definities: zie de meegeleverde OKD_v1.0.yml of de officiële standaard.

Onderwijscontext

Documentbeheer

De standaard koppelt documenten aan flows zoals inschrijfdocument, examenresultaat, BPV-document en diplomering; zie de officiële OKD-standaard voor de volledige flow-definities.

Beschikbaarheid & SLA

Eduarte Connect wordt aangeboden als beheerde dienst. Beschikbaarheid, onderhoud en support zijn vastgelegd in de partnerovereenkomst en bijbehorende SLA.

Uitgangspunten

• De API’s zijn ontworpen voor continue beschikbaarheid tijdens kantoor- en lesuren.
• Gepland onderhoud wordt vooraf aangekondigd via de gangbare communicatiekanalen en zo veel mogelijk buiten piekuren uitgevoerd.
• Storingen en vragen kunnen worden gemeld bij Eduarte via de beklende servicedesk meldingen
• Partner vragen kunnen worden gemeld bij info@eduarte.nl.

Let op: concrete SLA-cijfers (beschikbaarheidspercentage, reactietijden, onderhoudsvensters) worden vastgelegd in de partnerovereenkomst en zijn nog te bevestigen voor deze documentatie.

Versiebeheer & standaard

OKD is gebaseerd op OOAPI v5; versionering en wijzigingen volgen de landelijke OKD-standaard. Raadpleeg de officiële standaard voor de actuele versie en wijzigingen.