Rollen und Berechtigungen für API-Schlüssel

Jeder Elido API-Schlüssel ist mit einer Rolle verknüpft. Die Rolle bestimmt, was der Schlüssel tun kann. Die Wahl der am wenigsten mächtigen Rolle für jeden Anwendungsfall begrenzt den Schadensradius, falls ein Schlüssel jemals geleakt wird.

Die drei Rollen#

Rolle	Was sie tun kann
viewer	Links, Analysen und Workspace-Einstellungen lesen. Kann nichts erstellen, aktualisieren oder löschen.
editor	Alles, was ein viewer kann, plus Links erstellen/aktualisieren/löschen, Webhooks verwalten und Bulk-Importe ausführen.
admin	Alles, was ein editor kann, plus Workspace-Mitglieder, Abrechnung, API-Schlüssel und IP-Regeln verwalten.

Sie legen die Rolle fest, wenn Sie einen Schlüssel in Settings → API keys erstellen. Sie können die Rolle eines Schlüssels nach der Erstellung nicht mehr ändern – stellen Sie einen neuen Schlüssel mit der richtigen Rolle aus und widerrufen Sie den alten.

Welche Rolle zu verwenden ist#

Analyse-Dashboards und schreibgeschützte Integrationen — verwenden Sie viewer. Ein BI-Tool eines Drittanbieters, eine Statusseite, die Klickzahlen abruft, oder ein internes Reporting-Skript müssen Daten nur lesen.

CI/CD-Pipelines, die Links kürzen — verwenden Sie editor. Ihr Deployment-Skript, das Kampagnenlinks erstellt, Ihre CMS-Integration, die Kurz-URLs generiert, und die meisten Zapier/Make-Automatisierungen fallen hierunter.

Admin-Automatisierung — verwenden Sie admin nur dann, wenn die Integration tatsächlich Mitglieder oder die Abrechnung verwalten muss. Dies ist ungewöhnlich. Die meisten Integrationen, die sich nach „Admin“ anfühlen, sind eigentlich nur Editoren.

MCP server / AI agent — editor ist die richtige Standardeinstellung, es sei denn, der Agent muss Mitglieder einladen. Das Paket @elido/mcp-server berücksichtigt die Rolle des Schlüssels.

Rolle-zu-endpoint-Mapping#

Eine Kurzübersicht für gängige API-Aufrufe:

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

Die vollständige Referenz finden Sie unter /api.

Scope mismatch Fehler#

Wenn ein Schlüssel keine Berechtigung für einen endpoint hat, gibt die API Folgendes zurück:

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

Das Feld required_role sagt Ihnen genau, was Sie benötigen. Die Lösung besteht darin, einen neuen Schlüssel mit der höheren Rolle auszustellen (falls dies beabsichtigt ist) oder zu überdenken, ob die Integration diese Operation überhaupt durchführen sollte.

Häufige Fehler:

• Verwendung eines viewer-Schlüssels zum Erstellen von Links. Lösung: stellen Sie einen editor-Schlüssel aus.
• Verwendung eines editor-Schlüssels, um ein Teammitglied über ein Skript einzuladen. Lösung: stellen Sie einen admin-Schlüssel aus oder verwenden Sie stattdessen das Dashboard.
• Verwechslung der Workspace-Ebene-Mitgliedsrolle (Owner/Member) mit der API-Schlüsselrolle. Dies sind separate Konzepte. Ein Teammitglied mit „Member“-Zugriff kann dennoch einen admin-API-Schlüssel für seine eigenen Integrationen erstellen – seine Dashboard-Berechtigungen werden nicht auf den Schlüssel übertragen.

Fehlerbehebung#

403 auf einem endpoint, der erlaubt sein sollte. Überprüfen Sie die Schlüsselrolle in Settings → API keys — sie wird in der Spalte Role angezeigt. Wenn die Rolle korrekt aussieht, stellen Sie sicher, dass Sie den Header Authorization: Bearer <token> senden und nicht einen Basic auth Header oder einen Query-Parameter.

401 Unauthorized. Der Schlüssel ist entweder widerrufen oder das Token ist falsch. Überprüfen Sie die Spalte Status auf ein revoked-Abzeichen. Wenn der Schlüssel aktiv ist, stellen Sie sicher, dass Sie das vollständige Token bei der Erstellung kopiert haben.

Schlüssel funktioniert für Lesezugriffe, schlägt aber bei Schreibzugriffen fehl. Ihr Schlüssel ist wahrscheinlich ein viewer. Stellen Sie einen neuen editor-Schlüssel aus.

Ich benötige unterschiedliche Berechtigungen pro Integration. Stellen Sie einen Schlüssel pro Integration aus. Schlüssel können kostenlos erstellt und einzeln leicht widerrufen werden, daher gibt es keinen Grund, einen Schlüssel zwischen zwei Systemen zu teilen.