API-sleutelrollen en machtigingen

Elke Elido-API-sleutel heeft een gekoppelde rol. De rol bepaalt wat de sleutel mag doen. Door de minst krachtige rol te kiezen voor elke use case, beperk je de schade als een sleutel ooit lekt.

De drie rollen

Rol	Wat hij kan
viewer	Links, analytics en workspace-instellingen lezen. Kan niets aanmaken, bijwerken of verwijderen.
editor	Alles wat viewer kan, plus links aanmaken/bijwerken/verwijderen, webhooks beheren en bulk-imports uitvoeren.
admin	Alles wat editor kan, plus workspace-leden, facturering, API-sleutels en IP-regels beheren.

Je stelt de rol in wanneer je een sleutel aanmaakt in Instellingen → API-sleutels. Je kunt de rol van een sleutel na aanmaak niet meer wijzigen — geef een nieuwe sleutel uit met de juiste rol en trek de oude in.

Welke rol te gebruiken

Analyticsdashboards en alleen-lezen-integraties — gebruik viewer. Een BI-tool van derden, een statuspagina die klikaantallen ophaalt, of een intern rapportagescript hoeft alleen data te lezen.

CI/CD-pipelines die links verkorten — gebruik editor. Je deployscript dat campagnelinks aanmaakt, je CMS-integratie die korte URL's genereert, en de meeste Zapier/Make-automatiseringen vallen hieronder.

Adminautomatisering — gebruik admin alleen wanneer de integratie echt leden of facturering moet beheren. Dit is ongebruikelijk. De meeste integraties die "admin aanvoelen" zijn eigenlijk gewoon editors.

MCP-server / AI-agent — editor is de juiste standaardkeuze, tenzij de agent leden moet uitnodigen. Het pakket @elido/mcp-server respecteert de rol van de sleutel.

Rol-naar-endpoint-mapping

Een snelle referentie voor veelvoorkomende API-aanroepen:

GET    /v1/links              → viewer
POST   /v1/links              → editor
PUT    /v1/links/:id          → editor
DELETE /v1/links/:id          → editor
GET    /v1/analytics/clicks   → viewer
GET    /v1/workspace          → viewer
POST   /v1/workspace/members  → admin
POST   /v1/api-keys           → admin

De volledige referentie staat op /api.

Scope-mismatchfouten

Wanneer een sleutel geen toestemming heeft voor een endpoint, geeft de API het volgende terug:

{
  "error": "forbidden",
  "message": "this key requires the admin role to manage workspace members",
  "required_role": "admin",
  "key_role": "editor"
}

Het veld required_role vertelt je precies wat je nodig hebt. De oplossing is een nieuwe sleutel uitgeven met de hogere rol (als dat de bedoeling is), of heroverwegen of de integratie die bewerking überhaupt zou moeten doen.

Veelgemaakte fouten:

• Een viewer-sleutel gebruiken om links aan te maken. Oplossing: geef een editor-sleutel uit.
• Een editor-sleutel gebruiken om vanuit een script een teamlid uit te nodigen. Oplossing: geef een admin-sleutel uit, of gebruik in plaats daarvan het dashboard.
• De workspace-lidmaatschapsrol (Owner/Member) verwarren met de API-sleutelrol. Dit zijn afzonderlijke concepten. Een teamlid met "Member"-toegang kan nog steeds een API-sleutel met de rol admin aanmaken voor zijn eigen integraties — de dashboardrechten van het teamlid worden niet door de sleutel geërfd.

Problemen oplossen

403 op een endpoint dat toegestaan zou moeten zijn. Controleer de sleutelrol in Instellingen → API-sleutels — deze staat in de kolom Rol. Als de rol klopt, bevestig dan dat je de header Authorization: Bearer <token> verstuurt, en geen Basic-auth-header of queryparameter.

401 Unauthorized. De sleutel is ofwel ingetrokken, of de token klopt niet. Controleer de kolom Status op een revoked-badge. Als de sleutel actief is, controleer of je bij aanmaak de volledige token hebt gekopieerd.

Sleutel werkt voor lezen maar faalt bij schrijven. Je sleutel is waarschijnlijk een viewer. Geef een nieuwe editor-sleutel uit.

Ik heb per integratie andere rechten nodig. Geef per integratie één sleutel uit. Sleutels zijn gratis aan te maken en gemakkelijk individueel in te trekken, dus er is geen reden om een sleutel tussen twee systemen te delen.