Omniscol-API — authenticatietokens

Sleutel en token: twee verschillende objecten

Omniscol onderscheidt twee objecten die u niet mag verwarren.

Een sleutel is een blijvend object dat aan de kant van Omniscol bewaard blijft. Hij bundelt:

• een korte, willekeurig gegenereerde en openbare identificatie: die wordt in de lijst getoond en reist mee in elk token om aan te geven welke sleutel gecontroleerd moet worden;
• een beschrijvend label, dat u op elk moment kunt wijzigen;
• een optionele vervaldatum, die u op elk moment kunt wijzigen;
• een lang, willekeurig geheim, aan serverzijde aangemaakt, dat dienstdoet als cryptografische ondertekeningssleutel.

De identificatie, het label en de vervaldatum zijn beheergegevens: de identificatie is alleen een openbare verwijzing, geen geheim element. Het geheim daarentegen is het enige ondertekeningsmateriaal: het wordt willekeurig gegenereerd bij het aanmaken van de sleutel, blijft aan serverzijde, is niet te wijzigen en wordt nooit getoond of teruggegeven — niet bij het aanmaken en niet in de lijst met sleutels. En zelfs als het zou uitlekken, zou het niet volstaan om een token te vervalsen: de handtekening combineert het met een salt die eigen is aan het account en met een servergeheim, die evenmin ooit buiten Omniscol komen.

Een token is een op zichzelf staand JWT (JSON Web Token), ondertekend met het geheim van de sleutel. Dat is wat u aan het externe systeem doorgeeft. De ondertekende inhoud bevat het betrokken account, de lijst met toegestane endpoints, de sleutel waarvan het is afgeleid en zijn eigen vervaldatum.

Met andere woorden: een sleutel ondertekent, een token wordt ondertekend. Dezelfde sleutel kan meerdere tokens ondertekenen — allemaal te controleren met hetzelfde geheim, en dus allemaal samen ingetrokken zodra de sleutel verdwijnt.

Omniscol bewaart het token niet: het genereert het, toont het één keer en controleert het daarna bij elke aanroep opnieuw door de handtekening te herberekenen op basis van het geheim van de sleutel (HMAC SHA-256). Geen enkele bevoegdheid die het token draagt, kan dus worden gewijzigd zonder dat geheim.

Een token aanmaken

Het scherm Delen vindt u in Beheer → Import/Export op Premium-accounts. Het aanmaken gebeurt in twee stappen: u maakt eerst een sleutel aan en genereert daarna een token op basis van die sleutel.

1. Een sleutel aanmaken — vul een sprekend label in en, als de toegang tijdelijk is, een vervaldatum. Het label en de vervaldatum blijven achteraf te wijzigen; het ondertekeningsgeheim niet.
2. Een token genereren — selecteer de sleutel, vink de toegestane endpoints aan, kies eventueel een vervaldatum die alleen voor het token geldt, en genereer het JWT.

Bij het genereren toont Omniscol het token één enkele keer. Kopieer het meteen naar een secretsmanager: het wordt niet opnieuw getoond. De vervaldatum van het token staat in de ondertekende inhoud: die verandert u achteraf niet meer. Genereer een nieuw token om die datum te wijzigen.

Er zijn dus twee niveaus van vervaldatum, onafhankelijk van elkaar:

• vervaldatum van de sleutel — te wijzigen vanuit de lijst met sleutels; zodra die bereikt is, worden alle tokens die van deze sleutel zijn afgeleid geweigerd (de aanroep mislukt met een 401);
• vervaldatum van het token — vastgelegd bij het genereren, opgenomen in het JWT en daarna niet meer te wijzigen.

Toegestane endpoints

Een token geeft alleen toegang tot de endpoints die bij het genereren zijn aangevinkt: ga er nooit van uit dat het de hele API dekt. De toegestane lijst reist mee in het token en wordt bij elke aanroep gecontroleerd; een aanroep naar een niet-toegestaan endpoint wordt geweigerd (401).

Naast de afzonderlijke endpoints biedt de keuzelijst snelkoppelingen per module:

• de vermelding van een module op zich geeft toegang tot al zijn endpoints;
• de varianten per bewerking — lezen, wijzigen, aanmaken, verwijderen — beperken de module tot één soort aanroep.

Door “Rooster [lezen]” aan te vinken geeft u dus volledige leestoegang tot de roosters zonder ook maar iets aan schrijfrechten open te zetten, en zonder elk endpoint één voor één aan te vinken. Houd het zo krap mogelijk: geef alleen de modules en de bewerkingen die strikt noodzakelijk zijn voor de integratie.

Een token gebruiken

Twee gebruikelijke manieren om het token naar de API te sturen:

• HTTP-header: Authorization: Bearer <token> (aanbevolen).
• Query string: ?auth=<token> (handig om te debuggen, maar het verschijnt in de HTTP-logs — vermijd dit in productie).

Voorbeeld met curl, aan te passen met een echt endpoint uit de OpenAPI:

curl -H "Authorization: Bearer $TOKEN" \
  https://uw-school.omniscol.com/api/<module>/<endpoint>

OpenAPI-documentatie

Het scherm Import/Export toont een link OpenAPI 3.1 die de voor het account beschikbare specificatie opent in Swagger Editor. Daar vindt u:

• de lijst met aangeboden API-endpoints,
• de schema's van de uitgewisselde gegevens,
• de methoden en parameters,
• de verwachte antwoorden.

De specificatie wordt ook rechtstreeks door uw account geleverd, zonder authenticatie:

• /api/guest/openapi.json — specificatie in JSON-formaat;
• /api/guest/openapi.yaml (of /api/guest/openapi?yaml=true) — dezelfde inhoud in YAML-formaat;
• /api/guest/school_schema.json — JSON-schema van de gegevens van het account.

De volledige help voor uw AI-assistent

Het portaal publiceert de volledige Omniscol-help ook als één tekstbestand, klaar om als kennisbank te dienen voor een AI-assistent (Claude-project, aangepaste GPT…):

• omniscol.com/nl/llms-full.txt — de volledige gids in Markdown, beschikbaar in elke taal van de help (/en/llms-full.txt, /de/llms-full.txt…);
• omniscol.com/llms.txt — de index volgens de llms.txt-standaard, die AI-engines automatisch vinden.

Toegang intrekken

Het intrekken gebeurt op het niveau van de sleutel, niet van het afzonderlijke token.

Het scherm toont de sleutels waarmee tokens zijn gegenereerd. Een sleutel verwijderen wist het ondertekeningsgeheim aan de kant van Omniscol: vanaf dat moment kan geen enkele handtekening die van dat geheim is afgeleid nog gecontroleerd worden, en elke aanroep met een token uit die sleutel mislukt met een 401. Het is de afwezigheid van het geheim die de tokens ongeldig maakt, niet een intrekkingslijst.

Voor de ICT-afdeling zijn er twee gevolgen:

• Er is geen intrekking per token. Omniscol bewaart de uitgegeven JWT's niet en kan er geen enkel afzonderlijk uitschakelen: een token dat al gegenereerd is, blijft geldig tot zijn eigen vervaldatum, of tot zijn sleutel verwijderd of verlopen is.
• De vervaldatum van een sleutel wijzigen werkt onmiddellijk door op al zijn tokens: die datum vervroegen sluit de toegang af voor alle tokens die uit de sleutel zijn voortgekomen.

Aanbevolen werkwijze: verwijder meteen elke sleutel waarvan u vermoedt dat die is uitgelekt, en maak daarna een vervangende sleutel aan met een sprekend label.

Eén sleutel per doel en per gebruik

Omdat het intrekken per sleutel gebeurt, wijst u aan elke integratie een eigen sleutel toe (één externe toepassing = één sleutel). Het geheim van een sleutel ondertekent alleen zijn eigen tokens: die sleutel verwijderen maakt alleen de toegang van de betrokken integratie ongeldig, zonder de andere te raken.

Omgekeerd maakt één enkele sleutel die door meerdere systemen wordt gedeeld elke intrekking bruut: de gecompromitteerde sleutel verwijderen legt in één klap alle systemen stil die er gebruik van maakten.

Voor welke integraties

De API wordt doorgaans gebruikt voor:

• signagesystemen op maat (verder dan de eigen informatieschermen van Omniscol; zie Aanpassing van informatieschermen),
• externe dashboards die Omniscol met andere bronnen samenbrengen,
• koppelingen of synchronisaties met een ERP of een bedrijfsinformatiesysteem,
• MCP-compatibele AI-agenten die Omniscol via de MCP-server aanspreken; zie MCP — een externe AI-agent aansluiten.

Voor toegang die u delegeert aan een geïdentificeerde externe dienst (token met beperkt bereik, toestemming van de gebruiker, in te trekken door de client uit te schakelen) gebruikt u beter de OAuth2-server van Omniscol: zie OAuth2 / OIDC (aanbieder).