Entwickler-Leitfaden
Scope-Referenz
Feingranulare Berechtigungs-Scopes begrenzen, worauf ein API-Schlüssel oder OAuth-Client innerhalb eines Workspace zugreifen darf.
Überblick
Scopes sind durch Leerzeichen getrennte Zeichenketten, die an einen API-Schlüssel oder OAuth-Client gebunden sind. Trifft eine Anfrage ein, prüft die API die Scopes des Tokens gegen die angeforderte Operation. Das Modell entspricht dem von GitHub und Stripe: vertraut, prüfbar und leicht nachvollziehbar.
Scopes sind optional. Ohne Angabe hat die Zugangsdatei vollen Zugriff auf den Workspace (entspricht einem Admin). Wir empfehlen, je Integration nur die minimal nötigen Scopes zu vergeben.
Scopes
| Scope | Was er erlaubt | Methoden | Endpunkte |
|---|---|---|---|
polls:read | Umfragen, ihre Inhalte und Metadaten lesen. | GET | /polls, /polls/{id} |
polls:write | Umfragen erstellen, aktualisieren und löschen. | POST, PATCH, DELETE | /polls, /polls/{id} |
results:read | Aggregierte Ergebnisse je Folie und die Abstimmungsliste lesen. | GET | /polls/{id}/results, /polls/{id}/responses, /polls/{id}/votes |
responses:write | Antworten und Stimmen an Umfragen senden. | POST | /polls/{id}/responses, /polls/{id}/votes |
sessions:write | Live-Sitzungen erstellen und steuern. | POST | /sessions, /sessions/{id}/control |
sessions:read | Zustand einer Live-Sitzung lesen (Status, aktuelle Folie, Teilnehmerzahl). | GET | /sessions/{id} |
media:write | Medien (Bilder, YouTube) hochladen und ausliefern, um sie in Fragen zu nutzen. | POST | /media |
export:read | Ergebnisse als CSV-Datei oder PDF-Bericht herunterladen. | GET | /polls/{id}/export |
ai:write | KI zum Erstellen von Umfrageinhalten nutzen. | POST | /polls/{id}/branch |
Scopes bei API-Schlüsseln
Scopes von API-Schlüsseln werden bei jeder Anfrage durchgesetzt. Ein Schlüssel mit nicht-leerem Scope-Satz darf nur die davon abgedeckten Endpunkte aufrufen. Fehlt ein benötigter Scope, folgt 403 insufficient_scope. Ein Schlüssel ohne Scopes hat vollen Workspace-Zugriff (siehe Standard unten). Vergib die Scopes beim Anlegen im Entwicklerportal.
Scopes bei OAuth-Clients
OAuth-Clients setzen Scopes bei der Token-Ausgabe durch. Rufst du POST /api/oauth/token mit einem scope-Parameter auf, werden nur die dem Client bei der Erstellung zugewiesenen Scopes gewährt. Ein nicht zugewiesener Scope wird stillschweigend aus dem Token entfernt.
Wird in der Token-Anfrage kein scope gesendet, erbt das Token alle dem Client zugewiesenen Scopes (oder vollen Zugriff, wenn der Client keine hat).
Eine vollständige Einrichtung beschreibt der OAuth-2.0-Leitfaden.
Standard (keine Scopes angegeben)
Zugangsdaten ohne Scopes haben vollen Workspace-Zugriff, gleichbedeutend mit einem Admin. Geeignet für:
- Persönliche Automatisierung in einem Workspace, der dir gehört
- Prototyping und Entwicklung
Für Produktionsintegrationen, die über Teams oder mit Dritten geteilt werden, gib immer die minimal erforderlichen Scopes an.
Hast du noch Fragen?
Unser Team hilft dir gerne weiter.