Token-Scopes (Organisation vs. Kunde)
API-Tokens können optional mit einem Customer Scope erstellt werden:
- Organisation-weites Token: kann Ressourcen über alle Kunden der Organisation hinweg lesen/ändern.
- Customer-Scoped Token: kann nur Ressourcen (Websites, Wartungsfenster usw.) innerhalb dieses einen Kunden lesen/ändern.
Customer-Scoped Tokens sind für Agenturen und externe Integrationen empfehlenswert. Requests außerhalb des Scopes liefern 403 Forbidden.
Ein Customer-Scoped Token erreicht organisationsweite Pfade nie, unabhängig von der HTTP-Methode: Organisationseinstellungen und Abrechnung (/api/organizations/**, /api/organization/** außer GET /api/organization), Nutzer, Admin- und Plattform-Admin-Routen, Eskalationskonfiguration, Sonderpreise und eigene Felder, Incident Management, Anlegen und Löschen von Kunden. Solche Aufrufe antworten mit 403 und data.code: customerScopedTokenForbidden. Das Lesen von /api/organization und /api/package-configs bleibt möglich. Kein API-Token kann ein weiteres Token erzeugen.
Rollen und der Kunden-Scope
Jeder Request bringt zwei Dinge mit: eine Rolle (welche Art von Schreibzugriffen der Akteur ausführen darf) und einen Kunden-Scope (welche Kunden der Akteur sieht). Den Scope bestimmt die Kundenbindung des Tokens, bei einer Benutzer-Session die Kundenzuweisungen dieses Benutzers. Ein Aufruf braucht beides.
| Rolle | Wer | Scope |
|---|---|---|
admin | Administrator der Organisation | Immer organisationsweit. |
editor | Teammitglied der Organisation | Organisationsweit, sofern der Benutzer keinen Kunden zugewiesen ist; sonst auf diese Kunden beschränkt. |
readonly | Self-Service-Benutzer eines Kunden | Immer auf die zugewiesenen Kunden beschränkt. |
readonly ist die Self-Service-Rolle, mit der ein Kunde arbeitet. Innerhalb des eigenen Kunden-Scopes darf sie lesen und schreiben: Monitore, Wartungsfenster für ihren Kunden, Benachrichtigungskanäle ihres Kunden und so weiter. Was sie nie kann: organisationsweite Ressourcen anfassen, also organisationsweite (Nur-Tag-)Wartungsfenster, Organisationseinstellungen und Abrechnung, Benutzer, das Anlegen von Kunden. editor und admin sind die Organisationsrollen; ein editor mit Kundenzuweisungen wird auf diesen organisationsweiten Ressourcen genau wie ein kundengebundener Akteur behandelt.
Konkret erhält ein Akteur mit eingeschränktem Scope (ein Customer-Scoped Token, ein readonly-Benutzer, ein editor mit Kundenzuweisungen) 403 mit data.code: customerScopedTokenForbidden bei:
- Anlegen eines Kunden (
POST /api/customers) - Bearbeiten oder Löschen eines organisationsweiten Wartungsfensters (
PATCH/DELETE /api/maintenance-windows/:idauf ein Fenster ohne Kunden) - Organisationseinstellungen, Abrechnung, Benutzer und den übrigen oben genannten Pfaden
und ein Nur-Tag-Wartungsfenster, das er anlegt, wird an seinen einen Kunden gebunden statt organisationsweit zu werden (siehe Wartungsfenster erstellen).
Eine Ressource außerhalb deines Scopes ist ein 404
403 steht für das, was du darfst: eine Rolle, die nicht schreiben darf, ein Customer-Scoped Token auf einem Organisationspfad, ein verwalteter Monitor. Eine konkrete Ressource, die existiert, aber einem anderen Kunden oder einer anderen Organisation gehört, ist für dich nicht von einer unterscheidbar, die es nicht gibt: Die API antwortet 404 mit demselben data.code wie bei einer unbekannten ID (websiteNotFound, monitorNotFound, customerNotFound, statusPageNotFound, …). Lies ein 404 nicht als Beleg, dass eine ID frei ist, und erwarte kein 403 als Hinweis, dass etwas existiert.
Hinweis: Session-basierte Authentifizierung (Cookies) wird für die Web-Oberfläche verwendet, ist für Integrationen aber nicht empfohlen.