API documentatie
API-autorisatie
WATCH kent per gebruikersgroep welke schermen die groep mag openen. Sinds kort tellen diezelfde schermrechten ook mee wanneer iemand niet via een scherm werkt, maar via de API. Mag je de klantenschermen openen, dan mag je de klant-onderdelen van de API gebruiken. Mag je dat niet, dan word je geweigerd.
Deze pagina legt uit wat je daarvoor instelt, wat de keuzes betekenen, en wat een gebruiker te zien krijgt als een aanroep wordt geweigerd.
Voor wie is dit? Voor de beheerder die de API openzet voor een koppeling, een script of een AI-assistent. Wie zelf een koppeling bouwt vindt de technische beschrijving van alle onderdelen in de API referentie (Swagger).
Het idee: geen tweede rechtenlijst
De voor de hand liggende oplossing was een aparte lijst met API-rechten naast de bestaande schermrechten. Daar is bewust niet voor gekozen. Twee lijsten die hetzelfde bedoelen groeien uit elkaar, en jij bent degene die ze met de hand in de pas moet houden.
In plaats daarvan leent de API de rechten die er al zijn. Elk deel van de API is gekoppeld aan een of meer schermen. Wie zo'n scherm mag openen, mag dat deel gebruiken. Verandert er iets aan de rechten van een groep, dan verandert de API automatisch mee.
Wat je instelt, en waar
Het gaat om twee plaatsen. De eerste zet het geheel aan of uit, de tweede bepaalt per groep wat er gebeurt.
| Waar | Instelling | Wat het doet |
|---|---|---|
| Systeeminstellingen, blok api authorisation | API actief | Bedient deze installatie zijn API? Staat dit uit, dan wordt elke API-aanroep geweigerd. |
| Beheer > Autorisatiegroepen, per groep | schermautorisatie ook op API | Gelden de schermrechten van deze groep ook op de API? Drie standen, zie hieronder. |
API actief is een noodstop, geen fijnregeling. Uitzetten raakt niet alleen koppelingen van buitenaf: een deel van de schermen binnen WATCH haalt zijn gegevens op dit moment ook via de API op, en die stoppen dan eveneens — onder meer de boekhouding en de control-schermen. Het scherm waarschuwt daar zelf ook voor. Gebruik het als je de API in een keer dicht wilt hebben, en niet om te bepalen wie wat mag — dat laatste doe je per groep.
Staat API actief uit, dan is het keuzeveld op het groepenscherm niet eens zichtbaar. Mis je het daar, kijk dan eerst bij de systeeminstelling.
De drie standen per groep
Het keuzeveld staat op het groepenscherm, tussen de andere eigenschappen van de groep:
Je kiest een van drie standen. Het verschil zit hem in wat er gebeurt met een API-onderdeel dat aan geen enkel scherm gekoppeld is — inloggen zelf, bijvoorbeeld, of het opvragen van wie je bent. Voor zulke onderdelen bestaat nu eenmaal geen scherm.
| Stand (in de volgorde van de keuzelijst) | Onderdeel bij een scherm dat de groep niet mag openen | Onderdeel zonder gekoppeld scherm |
|---|---|---|
| geen API-autorisatie | toegestaan | toegestaan |
| ja, endpoints zonder menu-item worden geweigerd | geweigerd | geweigerd |
| ja, endpoints zonder menu-item zijn toegestaan | geweigerd | toegestaan |
geen API-autorisatie is de stand waarin er niets verandert. Elke groep staat daar in het begin op; je zet een groep pas om als je weet welke API-onderdelen die groep nodig heeft.
De laatste stand, ja, endpoints zonder menu-item zijn toegestaan, is bedoeld voor de periode waarin de koppelingen nog niet allemaal ingericht zijn: de schermrechten gelden al wel, maar een onderdeel waarvoor nog niets is ingesteld gaat er gewoon doorheen in plaats van te weigeren. Kies die als je de rechten wilt laten gelden zonder dat een vergeten koppeling meteen een storing wordt.
Welke API-onderdelen horen bij een scherm?
Op het scherm Autorisatie groepen staat achter sommige schermnamen een klein pictogram. Ga je er met de muis overheen, dan zie je welke API-onderdelen beschikbaar zijn voor iedereen die dat scherm mag openen.
Het pictogram verschijnt alleen als API actief aan staat en de groep niet op geen API-autorisatie staat. Zie je het nergens, dan is er niets mis: dan geldt de koppeling voor deze groep eenvoudigweg niet.
Let op de toevoeging "ook bereikbaar via … andere schermen". Hetzelfde scherm hangt in WATCH vaak onder meerdere modules — "Klanten" zit zowel onder Urenregistratie als onder Agenda & Planning. Een API-onderdeel is dan aan al die menu-ingangen gekoppeld, en één ervan volstaat. Het vinkje hier weghalen sluit dat API-onderdeel dus niet af: wie het via een ander scherm mag openen, houdt toegang. Wil je een API-onderdeel echt dichtzetten, loop dan alle schermen na die het openen.
Dat werkt ook de andere kant op, en dat is de bedoeling. Een scherm waarop je klanten, projecten en medewerkers kunt aanmaken geeft toegang tot alle drie, ook al is het niet het eigen beheerscherm van een van die drie.
Wat ziet iemand die geweigerd wordt?
Geen leeg scherm en geen stilte, maar een foutmelding die zegt welke regel er gold. Een kale "Forbidden" is niet te onderscheiden van een verlopen inlog of een verkeerd adres, en dan gaat de ontvanger gokken.
De melding komt terug als HTTP-status 403, met daarin het API-pad, de stand van de groep, de naam van de groep, en de menu-items waarvan er één volstaat:
{
"success": false,
"error": {
"message": "Your group holds no menu authorisation for any screen governing this route.",
"code": "FORBIDDEN",
"status": 403,
"details": {
"route_prefix": "documentation",
"policy": "STRICT",
"required_any_of": [20595],
"group": "Beheerder WATCH geheel"
}
}
}Er zijn twee soorten weigering, en ze lezen verschillend. Bij de ene mist de groep een recht — dat los je op door de groep het scherm te geven, of door een andere groep te gebruiken. Bij de andere is er voor dit API-onderdeel op deze installatie helemaal niets ingesteld; dat is geen ontbrekend recht maar een gat in de inrichting. De melding zegt welk van de twee het is, zodat niemand een middag zoekt naar een recht dat niet bestaat.
Staat de hele API uit via API actief, dan is het antwoord een 503 die die instelling noemt — dus ook daar hoef je niet naar te raden.
Volgorde van invoeren
- Laat alles op geen API-autorisatie staan. Er verandert dan niets, en je hebt de tijd om te kijken welke groepen de API eigenlijk gebruiken.
- Zet één groep om. Begin met de groep waarvan je het beste weet wat hij doet. Er is geen knop die het voor iedereen tegelijk aanzet: de stand per groep is de enige schakelaar, dus een misser raakt nooit meer dan die ene groep.
- Kijk wat er misgaat en vul aan. Elke weigering noemt het API-pad en de schermen die het openen. Gaat het om iets dat de gebruiker met de hand gewoon mág, dan ontbreekt er een koppeling — niet een recht.
- Daarna de volgende groep.
Stap 3 is geen formaliteit. Welke schermen een klant of project aanmaken is kennis die uit de organisatie komt en niet uit de software; dat zijn precies de koppelingen waar niemand vooraf aan denkt.
En als je MCP gebruikt?
Werk je met een AI-assistent via MCP, dan is er geen dubbele controle. MCP kent zijn eigen rechten per gereedschap, en die beslissen. De aanroepen die MCP daarna intern doet worden niet nog eens langs de schermrechten gelegd.
Dat is een keuze en geen omissie: met twee poorten op één handeling zou een wijziging in een schermrecht een MCP-gereedschap stukmaken om een reden die niets met MCP te maken heeft, en zou je niet kunnen zien welke van de twee weigerde. Het gereedschap is dus de eenheid waarop je autoriseert. Wat MCP doet wordt wel gewoon meegeschreven.
Samengevat
- De API leent de schermrechten die je toch al beheert — geen tweede lijst.
- API actief is de noodstop voor de hele API, inclusief WATCH-schermen die de API gebruiken.
- Per groep kies je of die rechten ook op de API gelden, en wat er gebeurt met onderdelen zonder gekoppeld scherm.
- Een onderdeel is vaak via meerdere schermen bereikbaar; één recht volstaat.
- Een weigering zegt altijd welke regel gold, met welk pad, welke groep en welk recht.