API-permissies overzicht

Per API-credential bepaal je precies wat een integratiepartner mag doen. Dit overzicht legt uit welke permissies er zijn en wat ze toegankelijk maken.

Anders dan voor gewone gebruikers werkt de Public API niet met vooraf gedefinieerde rollen. Je stelt per credential een eigen set permissies samen, zo ruim of zo beperkt als de partner werkelijk nodig heeft. Dat geeft je per partner volledige controle over wat zij in jullie data kunnen lezen of wijzigen.

Let op:: De API-machtigingen gelden organisatie-breed. De API-machtigingen ondersteunen geen machtiging op gemeente- of adviesorganisatieniveau.

Twee conventies om eerst te kennen

Voor je naar de losse permissies kijkt, helpt het om twee terugkerende achtervoegsels te herkennen.

Eindigt een permissie op .All, dan ziet de credential alle records van jouw organisatie. Dezelfde permissie zonder .All beperkt de credential tot wat zij zelf via de API heeft aangemaakt. Een partner die alleen z’n eigen evenementen wil terugzien, heeft genoeg aan de variant zonder .All.

Voor bijlagen bestaat daarnaast .Basic. Deze variant geeft alleen toegang tot de lijst en de metadata van bijlagen, niet tot het downloaden van de bijlage zelf.

Permissies voor evenementen

Evenementen zijn opgesplitst in twee niveaus van detail: een lichte basisweergave en de volledige details.

• Events.Basic.Read geeft toegang tot de basisweergave van eigen evenementen. Bedoeld voor partners die alleen overzichten willen tonen. Hierin ontbreken privacygevoelige gegevens zoals de naam en het telefoonnummer van de Organisator.
• Events.Basic.Read.All doet hetzelfde, maar voor alle evenementen van de organisatie.
• Events.Details.Read geeft toegang tot de volledige details van eigen evenementen.
• Events.Details.Read.All doet hetzelfde voor alle evenementen van de organisatie.
• Events.Details.ReadWrite maakt het mogelijk om eigen evenementen aan te maken, bij te werken en te verwijderen.
• Events.Details.ReadWrite.All doet dat voor alle evenementen van de organisatie.

Lees-permissies en schrijf-permissies stapelen logisch: een credential met Events.Details.ReadWrite.All kan ook alles lezen.

Permissies voor bijlagen

Bijlagen horen bij evenementen, maar krijgen een eigen set permissies omdat de inhoud (PDF’s, plattegronden, foto’s) gevoelig kan zijn.

• Events.Attachments.Read.Basic geeft alleen de lijst van eigen bijlagen, zonder downloaden.
• Events.Attachments.Read geeft de lijst plus de mogelijkheid om eigen bijlagen te downloaden.
• Events.Attachments.Read.All geeft lezen en downloaden van alle bijlagen van de organisatie.
• Events.Attachments.ReadWrite geeft het uploaden en verwijderen van eigen bijlagen.
• Events.Attachments.ReadWrite.All doet dat voor alle bijlagen van de organisatie.

Permissies voor adviezen

De API ondersteunt het aanmaken en uitlezen van evenementadviezen.

• Consults.Read geeft toegang tot eigen adviezen.
• Consults.Read.All geeft toegang tot alle adviezen van de organisatie.
• Consults.ReadWrite maakt het mogelijk om eigen adviezen aan te maken, bij te werken en te verwijderen.
• Consults.ReadWrite.All doet dat voor alle adviezen van de organisatie.

Permissies voor instellingen

Een aantal referentie-instellingen is op tenant-niveau te lezen. Hier bestaat geen variant zonder .All, omdat deze gegevens van de organisatie zelf zijn en niet aan een credential toebehoren.

• Settings.Cities.Read.All geeft toegang tot de plaatsen-instelling.
• Settings.Municipalities.Read.All geeft toegang tot de gemeenten-instelling.
• Settings.ConsultDisciplines.Read.All geeft toegang tot consult-disciplines, vaak gebruikt om discipline-ID’s in adviezen om te zetten naar weergavenamen.

Permissies voor geo-data

• Events.Wfs.Read.All geeft toegang tot de WFS-data van de organisatie. Dit zijn geo-overlays die bij evenementen en bijlagen horen, bedoeld voor partners die kaartmateriaal in hun eigen tooling willen tonen.

Hoe je een goede selectie maakt

Geef nooit ruimere permissies dan de partner echt nodig heeft. Twijfel je tussen wel of geen .All, kies dan eerst de variant zonder. Komt de partner er later achter dat zij meer toegang nodig hebben, dan breid je de credential gericht uit via Bewerken op de pagina API.

Voor de meeste lees-koppelingen is een combinatie als Events.Basic.Read.All plus Events.Details.Read.All voldoende. Schrijf-permissies geef je alleen als de partner aantoonbaar evenementen, adviezen of bijlagen moet kunnen aanmaken of wijzigen. Bij twijfel: vraag de partner concreet welke endpoints zij gaan aanroepen en koppel daar de minimaal benodigde permissie aan.

Wil je weten waar je deze permissies aan een credential koppelt? Lees [API-credentials beheren]. Wil je een nieuwe credential aanvragen? Lees [API-sleutel aanvragen].