Rechten van API-sleutels: least privilege voor linktools

Rechten van API-sleutels bepalen wat een gelekte sleutel kan slopen. Bij een linktool is de veilige standaard een sleutel die aan één werkruimte is gebonden, is begrensd op de laagste rol die de taak aankan, als hash met pepper is opgeslagen, een eigen limiet heeft en verloopt. Een sleutel die alleen links aanmaakt hoort niet aan webhooks, leden of facturatie te komen, en hij mag nooit een admin-endpoint openen. Dat is least privilege, en het meeste ervan komt neer op keuzes die je maakt in de dertig seconden dat het aanmaken van de sleutel duurt.

Ik heb het afgelopen jaar veel automatiseringsopzetten gelezen en het patroon herhaalt zich: iemand plakt op vrijdagmiddag zijn eigen almachtige sleutel in n8n, het werkt, en niemand denkt er nog aan tot die persoon vertrekt of de export van de workflow in een gedeelde schijf belandt. De rest van dit artikel behandelt hoe scopes en rollen van API-sleutels werken in een product voor korte links, wat elke rol echt kan en hoe je een sleutel aan een automatiseringstool geeft zonder de werkruimte weg te geven.

Het sluit aan op onze bredere beveiligingschecklist voor URL-verkorters, die scannen, webhookondertekening en auditlogs over het hele platform behandelt. Deze gaat in op de sleutel zelf.

Wat rechten van API-sleutels betekenen in een linktool

De API van een linktool raakt meer dan links. Hetzelfde token dat go.example.com/spring-sale aanmaakt, kan, afhankelijk van zijn rechten, klikanalytics lezen, een eigen domein toevoegen, een lid uitnodigen of een webhook registreren die elk event naar een externe server stuurt. Dat laatste vind ik eng. Een webhook is een permanente datastroom die wie hem maakt naar elke gewenste server kan richten, en niemand in je team merkt dat per se in weken.

Rechten hebben dus drie assen. Waar werkt de sleutel (welk account of welke werkruimte)? Wat kan hij daar (lezen, schrijven, beheren)? En hoe lang, en hoe snel? De definitie van least privilege in de NIST-woordenlijst (geraadpleegd op 2026-10-24) zegt dat elke entiteit de minimale bevoegdheden krijgt die ze voor haar functie nodig heeft, en alle drie de assen horen daarbij. Een sleutel met alleen leesrechten die nooit verloopt en geen limiet heeft, is in de tijd nog steeds te ruim bevoegd.

API-sleutels per werkruimte: één sleutel, één werkruimte

Bij Elido wordt elke sleutel binnen een werkruimte gemaakt en blijft daar. Roep je er de endpoints van een andere werkruimte mee aan, dan krijg je een 404, hetzelfde antwoord als voor een werkruimte die niet bestaat, zodat een sleutel niet eens kan bevestigen dat andere werkruimten er zijn.

Dit telt zwaarder dan het klinkt. Bureaus en grotere teams horen vaak bij vijf of tien werkruimten. Als een persoonlijke sleutel alles erfde wat zijn maker kon bereiken, zou één gelekt token van één klantproject elke klant openen. API-sleutels per werkruimte verkleinen de reikwijdte van de schade tot één werkruimte.

De sleutel is ook begrensd op de rol die bij het aanmaken is gekozen, en overstijgt nooit de huidige rol van zijn maker. Het effectieve toegangsniveau is de laagste van de twee. Degradeer de admin die een sleutel maakte naar editor, dan zakt de sleutel mee. Aangepaste rechten van dat lid vervallen ook zodra de rol van de sleutel de lagere is, omdat die de persoon beschrijven en niet de sleutel.

API-sleutels op basis van rollen: wat elke rol kan

Elido-sleutels gebruiken dezelfde vier rollen als mensen: viewer, editor, admin en owner. Je kiest er een bij het aanmaken van de sleutel; laat je het weg, dan wordt het standaard editor, wat de gebruikelijke automatiseringstaak van links aanmaken en analytics lezen dekt zonder admin-bereik.

Zo ziet dat er in de praktijk uit voor de dingen die integraties meestal raken.

Een rapportagedashboard dat klikaantallen in een BI-tool trekt heeft viewer nodig. Een Google Sheets-taak die campagnelinks aanmaakt heeft editor nodig. Bijna niets in dagelijkse automatisering heeft admin nodig, en een owner-sleutel zou ik als geurtje behandelen: owner bestaat voor de mensen die de werkruimte runnen, en ik kan geen automatiseringstaak bedenken die het nodig heeft.

Twee grenzen zijn goed om te weten. Alleen admins en owners hebben het recht api_keys.manage, dus een viewer- of editor-sleutel kan geen sleutels weergeven of intrekken. En een sleutel aanmaken, of de limiet ervan wijzigen, vereist een ingelogd persoon: een API-sleutel van welke rol dan ook krijgt een 403 ("this action requires an interactive session"). Een gelekte admin-sleutel kan dus geen sleutel zonder vervaldatum als vervanger maken. Hij kan nog wel sleutels weergeven en intrekken. En geen enkele sleutel van welke rol dan ook bereikt de admin-API van het platform. Dat oppervlak weigert authenticatie met een API-sleutel gewoon met een 403 en de melding "admin access requires an interactive session". Een sleutel is voor een integratie van een werkruimte, en dat is alles wat hij opent.

Waarom webhookbeheer een admin-sleutel nodig heeft

Dit is het punt dat mensen verrast. De lijst met webhook-endpoints lezen mag elk lid, ook viewer-sleutels. Maar een endpoint aanmaken, wijzigen waar het naartoe wijst of een levering opnieuw afspelen vereist het recht workspace.edit, dat alleen admin en owner hebben.

De redenering is het eerdere probleem van de permanente datastroom. Een editor kan duizend links aanmaken en dat merk je. Een editor die een catch-all webhook naar zijn eigen server zou kunnen toevoegen, ontvangt vanaf dat moment ongemerkt elk linkevent. Wijzigingen aan webhooks liggen dus bij dezelfde mensen die werkruimte-instellingen kunnen wijzigen.

Stel webhooks in de praktijk één keer met de hand in als admin in het dashboard. Geef de automatisering die ze verwerkt daarna een editor- of viewer-sleutel voor haar API-aanroepen. Koppel je webhooks voor linkevents aan Slack of een CRM, dan heeft de ontvangende kant helemaal geen Elido-sleutel nodig; die heeft het ondertekeningsgeheim nodig om payloads te verifiëren.

Wil je bewijs voordat je iets aansluit? Maak een gratis werkruimte aan, genereer een viewer- en een editor-sleutel en probeer met allebei dezelfde schrijfaanroep. De 403 op de viewer-sleutel vertelt je meer dan elke tabel.

Hoe sleutels worden opgeslagen: pepper, hash en voorvoegsel

Een token ziet eruit als elido_ gevolgd door 52 tekens base32, gegenereerd uit 32 willekeurige bytes. Je ziet het geheel precies één keer, in het antwoord op de aanmaakaanroep. Daarna is het aan onze kant voorgoed weg.

Wat we bewaren is een HMAC-SHA256 van het token, gesleuteld met een pepper aan de serverkant die in de configuratie van de applicatie staat, niet in de database. Bij elk verzoek wordt het binnenkomende Bearer-token (het schema uit RFC 6750, geraadpleegd op 2026-10-24) op dezelfde manier gehasht en op hash opgezocht. Een gestolen databasedump is dus een lijst hashes die niemand zonder de pepper kan controleren. Geen pepper, geen start: de productieservice weigert op te starten zonder dat er een is ingesteld.

Voor je eigen administratie bewaren we de eerste acht tekens na elido_ als weergavevoorvoegsel, en de pagina met API-sleutels toont dat voorvoegsel naast de naam, rol, aanmaakdatum, vervaldatum, laatst-gebruikte tijd en laatst-gebruikte IP van de sleutel, plus het totale aantal en het aantal mislukte verzoeken. Duikt een sleutel ergens in een log op, dan vertelt het voorvoegsel welke het is. Niemand hoeft het volledige geheim te zien.

Limieten, vervaldatum en rotatie van API-sleutels

Elke sleutel krijgt een eigen tokenbucket, los van de limiet per werkruimte, zodat één op hol geslagen workflow het budget van al het andere niet opeet. Een ingelogde admin kan het tempo van één sleutel overschrijven van 1 tot 10.000 verzoeken per seconde en de burst van 1 tot 20.000, of de overschrijving wissen om terug te vallen op de standaard. Boven de limiet krijgt de sleutel een 429 met Retry-After: 1 en X-RateLimit-Scope: api_key, zodat je retrylogica een sleutellimiet van een werkruimtelimiet kan onderscheiden. De gids over limieten en idempotentie behandelt hoe je netjes terugschakelt.

Een vervaldatum is optioneel en wordt bij het aanmaken ingesteld als RFC 3339-tijdstempel. Zodra die verstrijkt, matcht de sleutel gewoon niet meer. Intrekken is één DELETE. Die is bovendien idempotent.

Er is geen aparte knop "roteren", en ik mis hem niet. Rotatie gaat in drie stappen:

1. Maak een nieuwe sleutel met dezelfde rol en een verse vervaldatum.
2. Zet hem in het credentialarchief van de tool en bevestig dat een aanroep slaagt.
3. Trek de oude sleutel in en controleer in de lijst dat de laatst-gebruikte tijd niet meer verschuift.

Elke stap komt in het auditlog van de werkruimte: api_key.created met naam en rol, api_key.revoked en api_key.rate_limit_set voor overschrijvingen. Daarnaast draait elke vijf minuten een achtergrondscan die elke sleutel markeert met meer dan 1.000 verzoeken waarvan meer dan 30% mislukte. De markering komt in het auditlog en op de sleutel. Geen automatische intrekking. Een sleutel afknallen is een menselijke beslissing, want een stroom 404's is even vaak een kapotte workflow als een aanvaller.

Least privilege-API-sleutels aan n8n, Make en Zapier geven

Automatiseringsplatforms zijn de plek waar sleutels worden vergeten. Ze staan in een credentialarchief, worden gekopieerd naar geëxporteerde workflow-JSON en overleven de persoon die ze instelde. Twee gewoonten helpen:

• Eén sleutel per tool en per workflowfamilie, naar de tool genoemd ("n8n: campaign sheets"). Intrekken breekt dan precies één ding, en het auditlog vertelt welke tool wat deed.
• Editor voor alles wat links aanmaakt, viewer voor alles wat alleen leest, en een vervaldatum op beide.

Dat is de lijst; de rest is beoordelingsvermogen. De OWASP Secrets Management Cheat Sheet (geraadpleegd op 2026-10-24) is een goede lectuur over tokens buiten logs en exports houden, en daar lekken automatiseringssleutels meestal.

Voor de toolspecifieke opzet zet de gids voor de n8n-URL-verkorter de sleutel in een Header Auth-credential, en de vergelijking Make vs IFTTT vs n8n vs Zapier laat zien waar elk platform hem bewaart. Zapier verbindt via hetzelfde token, volgens de uitleg over Zapier-automatisering. Voor CI of alles wat het vertrek van een persoon moet overleven past een machinegebruiker beter: een serviceaccount met een eigen token, los van de sleutel van een mens. Net als sleutels worden machinegebruikers aangemaakt door een ingelogde admin, nooit door een token.

En de reden dat een sleutel nooit admin-endpoints mag openen is precies deze overdracht. Zodra een token in een tool van derden staat, kan iedereen met bewerkrechten op de workflows van die tool hem gebruiken. Je vertrouwt iedereen aan hun kant, niet alleen die aan jouw kant.

Tokens per scope zijn gepland, niet live

Rollen zijn bewust grof, en soms te grof. Een editor-sleutel die alleen links aanmaakt, kan ze ook verwijderen, omdat verwijderen bij de rol editor hoort. De oplossing zijn tokens per scope, zoals links:write of analytics:read, rechtstreeks aan een sleutel gehangen bovenop rollen.

Dat staat op onze roadmap en is niet uitgebracht. Nu bestaan de rechten van een sleutel uit zijn werkruimte plus zijn rol, niets fijners. Heb je nu strakkere controle nodig, dan zijn de twee hefbomen een lagere rol en een korte vervaldatum, plus aparte sleutels per taak zodat de reikwijdte van elk klein blijft. De API-quickstart en de API- en SDK-referentie tonen het huidige sleutelmodel in werkende code, en teams die ook controle op identiteitsniveau willen, kunnen lezen over SCIM en SSO voor marketingtools.

Lees de cornerstone: de beveiligingschecklist voor URL-verkorters behandelt de maatregelen rond de sleutel, van URL-scanning tot IP-allowlists.

Gerelateerd op de blog

• URL-verkorter-API: een quickstart van 30 minuten in vijf talen
• n8n-URL-verkorter: HTTP Request-node of Elido-communitynode
• Automatisering van korte links: Make vs IFTTT vs n8n vs Zapier
• Webhooks voor linkevents
• GitHub Actions-URL-verkorter: korte links vanuit je CI