API-token

Met een API-token kan externe software de API-endpoints van Omniscol namens de school aanroepen: om te lezen en, als er schrijvende API-endpoints zijn geselecteerd, ook om te schrijven.

Dat is krachtig — ga er dus zorgvuldig mee om.

Genereren

Een token genereert u in Delen (Import/Export > Delen). U geeft op:

• een sleutel (in Omniscol gegenereerd, met een label en een eventuele vervaldatum; die vervaldatum kunt u later nog wijzigen),
• een bereik: de lijst met API-endpoints die dit token mag aanroepen (geef alleen wat strikt noodzakelijk is),
• eventueel een vervaldatum van het token. Die datum wordt in het gegenereerde JWT opgenomen en kan daarna niet meer worden gewijzigd.

Zodra u de sleutel verwijdert of zodra die verloopt, worden de daarvan afgeleide tokens onmiddellijk ingetrokken. Wilt u de vervaldatum van één afzonderlijk token wijzigen, genereer dan een nieuw JWT.

Gebruik

Het token geeft u mee in de HTTP-header Authorization: Bearer <token>, of (minder aan te raden in productie) in de URL via ?auth=<token>.

Aanbevolen werkwijzen

• Eén sleutel per integratie — dat maakt het afzonderlijk intrekken eenvoudig.
• Minimaal bereik — vink alleen de API's aan die u nodig hebt, niet standaard alles.
• Vervaldatum op het juiste niveau — gebruik de vervaldatum van de sleutel om een langlopende integratie te sturen; gebruik de vervaldatum van het token voor tijdelijke toegang die niet meer te wijzigen is.
• Periodieke rotatie — genereer de sleutel elke 6-12 maanden opnieuw.
• Niet in Git — het token mag niet in het versiebeheer van een openbare repository belanden. Gebruik de omgevingsvariabelen van uw server.

Verschil met OIDC / SSO

Om echte gebruikers te laten inloggen met hun institutionele identiteit, gebruikt u OIDC / SSO. Het API-token is bedoeld voor technische server-naar-serverintegraties, niet voor het dagelijkse inloggen van gebruikers.