1. Beschrijf de taak zonder meteen een sleutel te maken
Schrijf eerst op wat de externe toepassing moet kunnen: welk soort dossier, alleen lezen of ook wijzigen, en waarvoor? “Alles synchroniseren” is te ruim als de echte taak alleen bestaat uit een overzicht van installaties. Begin bij de kleinste gegevensverzameling die de taak daadwerkelijk nodig heeft.
Een servicesleutel geeft toegang tot één MANE. Alleen de eigenaar beheert deze sleutels via Instellingen → API & webhooks. Laat de verantwoordelijke daarom de taak en toegang samen beoordelen. Een collega die de flow bouwt heeft niet vanzelf bevoegdheid om bredere bedrijfsgegevens beschikbaar te maken. Dit stappenplan voert geen koppeling uit en maakt geen sleutels aan.
2. Zoek de technische objectnaam op
Open Wat spreek je aan? bij de API-instellingen. Kies het bedoelde object en neem het endpoint en de scopes uit de catalogus over. Het zichtbare label, de object-ID, de route en de veldsleutels hebben ieder een andere functie. Een schermtitel zoals Installaties is geen reden om zelf een technische sleutel te raden.
Alleen wanneer de catalogus werkelijk installaties als object-ID toont, past het voorbeeld /objects/installaties/records bij dat object. Combineer de route met het API-basisadres uit je eigen werkruimte. Gebruik de bijbehorende veldpaden voor je gegevensselectie. Een voorbeeld in een artikel vervangt de actuele catalogus niet.
3. Kies de objectscope en vermijd de brede omweg
Voor het voorbeeldobject beschrijft MANE objects.installaties:read als leesrecht voor de eigen objectroute. Dat recht geeft niet tegelijk toegang tot GET /records, andere objecten of de volledige catalogus. Een verzoek naar de brede route kan dus worden geweigerd terwijl de beperkte sleutel precies goed is ingesteld.
Voeg in dat geval niet gedachteloos records:read toe om de fout weg te krijgen. Die scope geeft toegang tot de brede verzameling relatie- en eigen dossierrecords en past niet bij de bedoeling “alleen dit object”. Controleer eerst of de toepassing de juiste objectroute gebruikt. Geef schema:read alleen afzonderlijk wanneer de toepassing ook de inrichting moet kunnen ontdekken.
4. Houd lezen, schrijven en de omvang van de toegang apart
Een leesflow heeft geen schrijfrecht nodig. Moet de koppeling later gegevens veranderen, beoordeel dan opnieuw welke handelingen nodig zijn. Wijzigrechten geven in MANE niet automatisch leesrechten. Voor het ophalen van een actuele revisie is workspace:read of een passend leesrecht nodig; een wijziging kan daarnaast eigen documentcontroles hebben.
Een objectscope betekent niet “alleen deze ene installatie” of “alleen het veld onderhoudsdatum”. De documentatie beschrijft de grens op objectniveau. Beloof dus geen record- of veldbeperking die hiermee niet is aangetoond. Welke waarden de flow werkelijk gebruikt, hoort bovendien bij haar eigen inrichting en controle. Een gerichte uitvoerselectie is niet hetzelfde als een kleinere toegangsbevoegdheid.
5. Fictief voorbeeld: alleen installaties lezen
Een fictief onderhoudsbedrijf wil in een eigen toepassing een overzicht van zijn installatiedossiers tonen. In de gecontroleerde MANE-catalogus heet het object in dit voorbeeld installaties. De eigenaar en bouwer maken een korte rechtenkaart: doel — installatieoverzicht; route — /objects/installaties/records; handeling — lezen; scope — objects.installaties:read; schrijven — niet nodig.
Ze noteren ook wat buiten de taak valt: geen brede /records-route, geen wijziging van dossiers en geen beheer van objectinrichting. De echte sleutel komt niet op de kaart. Wanneer de toepassing toch om records:read vraagt, onderzoekt de bouwer eerst waarom de brede route wordt gebruikt. Het bedrijfsdoel is niet veranderd doordat een eerste verzoek faalt.
Controleer de toegestane leesroute in een passende testcontext met zo weinig mogelijk gegevens. Noteer methode, route, HTTP-status en welke objectsoort terugkomt, zonder klantinhoud of geheimen te loggen. Een weigering op een niet-toegestane leesroute kan juist de bedoelde uitkomst zijn. Voer geen schrijfproef in productie uit om te bewijzen dat de sleutel níét mag schrijven. Dit voorbeeld is een ontwerp, geen uitgevoerde beveiligingstest.
6. Bewaar het geheim buiten je werknotities
De volledige servicesleutel verschijnt één keer. Bewaar haar in de daarvoor bedoelde beveiligde credentialvoorziening van de externe toepassing, niet in een gedeelde notitie, screenshot of voorbeeld-URL. MANE adviseert de Authorization-header niet te loggen en geen sleutel in URL-queryparameters te zetten.
Geef de verbinding een herkenbare naam en kies een passende geldigheidsduur uit de aangeboden opties. Houd bij wie de koppeling beheert en wanneer die opnieuw wordt beoordeeld. Bij vervanging controleer je de nieuwe verbinding met een leesverzoek voordat je de oude sleutel intrekt. De actuele documentatie beschrijft de volgorde; probeer een verloren sleutel niet uit de opgeslagen controlewaarde terug te halen.
7. Stop toegang en meldingen bewust
Wordt de koppeling niet meer gebruikt, dan kan de eigenaar de betreffende sleutel intrekken. Volgende verzoeken worden geweigerd. Controleer afzonderlijk of er ook een webhookabonnement voor die externe toepassing bestaat. Een API-sleutel intrekken beëindigt dat abonnement niet automatisch; een melding die al onderweg is kan nog aankomen.
Bewaar bij de rechtenkaart de gekozen route, scopes, beheerder en het gecontroleerde resultaat, maar nooit het geheim. De eindvraag is niet alleen “werkt de koppeling?”, maar ook “werkt zij met precies de toegang die voor deze taak bedoeld is?”. Voor conflicten, paginering en veilig herhalen blijven de afzonderlijke API-instructies nodig.
