Berechtigungen je Endpunkt
Welche Rolle, welche Token-Art und welchen Token-Scope jeder Endpunkt braucht, und mit welchem Fehlercode ein abgewiesener Aufruf antwortet.
Jeder Aufruf wird in dieser Reihenfolge geprüft. Die erste Prüfung, die scheitert, bestimmt die Antwort:
- Anmeldung. Kein Token, oder ein widerrufenes, abgelaufenes oder vertipptes:
401 unauthorized. - Token-Art. Ein kundengebundenes Token auf einem organisationsweiten Pfad:
403 customerScopedTokenForbidden. Ein Token mit Scopes, dem der Scope des Pfads fehlt:403 apiTokenScopeForbidden. Meldung unddata.requiredScopenennen den fehlenden Scope, zum Beispielapi.write.monitors. Siehe Token-Scopes. - Rolle. Ein Organisations-Token (
wsm_…) handelt mit der aktuellen Rolle des Nutzers, der es angelegt hat. Ist dieser Nutzer deaktiviert oder gelöscht, handelt das Token alsreadonly. Alte Tokens ohne hinterlegten Aussteller handeln alsadmin. Eine nicht zugelassene Rolle bekommt403mit dem Code aus der Tabelle unten. - Kundenbereich.
readonly-Nutzer, Editoren mit Kundenzuordnung und kundengebundene Tokens erreichen nur ihre eigenen Kunden. Eine einzelne Ressource außerhalb dieses Bereichs antwortet mit404und dem Nicht-gefunden-Code der Ressource, nie mit403. Ein API-Token, ob organisationsweit oder kundengebunden, folgt der aktuellen Rolle und Kundenzuordnung des Nutzers, der es angelegt hat: Ist dieser Nutzer Kunden zugeordnet, erreicht das Token nur diese Kunden (ein kundengebundenes Token erreicht seinen Kunden nur, solange der Nutzer ihn noch hat). Ist der Nutzer deaktiviert oder gelöscht, erreicht das Token keinen Kunden mehr. - Modul. Statusseiten brauchen das Statusseiten-Modul (
403 statusPagesModuleDisabled). Incident Management muss für die Organisation aktiviert sein (403 imNotEnabled).
Jeder abgewiesene Aufruf trägt einen stabilen data.code und eine englische statusMessage, die sagt, was fehlt. Verzweige auf den Code; der Text kann sich ändern.
Rollen: admin und editor sind Organisationsrollen, readonly ist die Self-Service-Rolle des Kunden, responder gibt es nur für Incident Management. Global Supporter ändern nie Kundendaten (403 forbidden). Agent-Tokens (wsma_…, verbundene Apps) erreichen nur die Pfade, die ihre Scopes erlauben; jeder andere Pfad antwortet mit 403 agentTokenReadOnly und data.reason.
Monitore
| Methode | Pfad | Wer darf aufrufen | Scope | Abweisung mit |
|---|---|---|---|---|
GET | /api/websites/:id, /api/<type>-monitors/:id | Jede Rolle innerhalb ihres Kundenbereichs | api.read.monitors | 404 websiteNotFound / monitorNotFound |
POST | /api/websites, /api/<type>-monitors | admin, editor. readonly und kundengebundene Tokens legen self_service-Monitore für den eigenen Kunden an, wenn das Paket Self-Service erlaubt. Nur admin darf managementType setzen. | api.write.monitors | forbidden, selfServiceNotAllowed, selfServiceQuotaReached, Kontingent-Codes |
PATCH | /api/websites/:id, /api/<type>-monitors/:id | admin, editor. Kundengebundene Aufrufer ändern self_service-Monitore, managed nur mit canEditManaged. managementType ändern braucht einen organisationsweiten admin. | api.write.monitors | forbidden, managed_by_organization, managementTypeOrgOnly |
DELETE | /api/websites/:id, /api/<type>-monitors/:id | Wie PATCH, aber nie readonly (auch kein Token, das dieser Nutzer angelegt hat) | api.write.monitors | readonlyMayNotDelete, managed_by_organization |
POST | /api/websites/:id/heartbeat-token/rotate | Wie PATCH | api.write.monitors | wie PATCH |
GET, POST, DELETE | /api/monitor-tags | Jede Rolle innerhalb ihres Kundenbereichs | api.read.monitors / api.write.monitors | forbidden, badRequest |
GET | /api/tags, /api/tags/:id | Jede Rolle der Organisation | api.read.monitors | 404 tagNotFound |
POST, PATCH, DELETE | /api/tags, /api/tags/:id | Jede Rolle; kundengebundene Aufrufer legen nur Tags ihrer Kunden an und ändern nur diese, nie organisationsweite Tags | api.write.monitors | forbidden, authorizingUserUnresolved |
GET | /api/maintenance-windows/:id | Jede Rolle innerhalb ihres Kundenbereichs | api.read.monitors | forbidden |
POST | /api/maintenance-windows | Jede Rolle außer Global Supportern. Kundengebundene Aufrufer verankern das Fenster an ihrem Kunden. | api.write.monitors | forbidden, tagOnlyNeedsCustomer |
PATCH, DELETE | /api/maintenance-windows/:id | Kundenfenster: innerhalb des Kundenbereichs. Organisationsweite Fenster: admin oder editor mit organisationsweitem Zugriff. | api.write.monitors | forbidden, customerScopedTokenForbidden |
GET | /api/monitoring-locations/countries | Jeder angemeldete Aufrufer | api.read.monitors | - |
<type> ist dns, ftp, icmp, imap-pop, smtp, ssh oder tcp; alle sieben folgen denselben Regeln.
Kunden
| Methode | Pfad | Wer darf aufrufen | Scope | Abweisung mit |
|---|---|---|---|---|
GET | /api/customers, /api/customers/:id | Jede Rolle; eingeschränkte Aufrufer sehen ihre eigenen Kunden | api.read.customers | 404 customerNotFound |
POST | /api/customers | admin, organisationsweiter editor. Keine kundengebundenen Tokens. Berechtigungsfelder wirken nur für admin. | api.write.customers | forbidden, customerScopedTokenForbidden |
PATCH | /api/customers/:id | admin, editor. Paket oder Berechtigungsfelder ändern braucht admin. | api.write.customers | forbidden, packageOrgOnly |
DELETE | /api/customers/:id | admin, editor (ein Editor mit Kundenzuordnung nur innerhalb dieses Bereichs und nie den letzten Kunden; userAction=delete bleibt admin). Keine kundengebundenen Tokens. | api.write.customers | forbidden, customerUserDeleteAdminOnly, cannotDeleteOwnLastCustomer |
POST | /api/customers/:id/ips, /api/customers/:id/domains | Jede Rolle innerhalb ihres Kundenbereichs, auch readonly (als self_service, wenn das Paket es erlaubt) | api.write.customers | forbidden, selfServiceNotAllowed, selfServiceQuotaReached, Kontingent-Codes |
GET | /api/customer-ips/:id, /api/customer-domains/:id | Jede Rolle innerhalb ihres Kundenbereichs | api.read.customers | 404 ipNotFound / domainNotFound |
PATCH | /api/customer-ips/:id, /api/customer-domains/:id | admin, editor; kundengebundene Aufrufer für self_service-Einträge | api.write.customers | forbidden, managed_by_organization, managementTypeOrgOnly |
DELETE | /api/customer-ips/:id, /api/customer-domains/:id | Wie PATCH, nie readonly | api.write.customers | readonlyMayNotDelete |
Organisation
Alle Pfade dieses Abschnitts sind für kundengebundene Tokens gesperrt (customerScopedTokenForbidden), außer GET /api/organization und GET /api/package-configs.
| Methode | Pfad | Wer darf aufrufen | Scope | Abweisung mit |
|---|---|---|---|---|
GET | /api/organization, /api/package-configs | Jede Rolle der Organisation | api.read.organization | - |
PATCH | /api/organization | admin. API-Tokens können automatische Upgrades und die MFA-Richtlinie nicht ändern. | api.write.organization | forbidden, nonUserSessionForbidden |
GET | /api/users | Jede Rolle; eingeschränkte Aufrufer sehen die Nutzer ihrer Kunden | api.read.organization | - |
POST, GET, PATCH, DELETE | /api/users, /api/users/:id | admin mit organisationsweitem Zugriff | api.read.organization / api.write.organization | forbidden, customerScopedTokenForbidden, globalUserProtected |
| alle | /api/custom-fields, /api/custom-fields/:id | Lesen: jede Rolle. Ändern: admin. | api.read.organization / api.write.organization | forbidden |
| alle | /api/escalation-config/:id | admin mit organisationsweitem Zugriff, auch zum Lesen | api.read.alerts / api.write.alerts | forbidden, customerScopedTokenForbidden |
GET | /api/organization/reports/:id | Jede Rolle der Organisation | api.read.reports | 404 notFound |
POST, PATCH, DELETE | /api/organization/reports, /api/organization/reports/:id | admin | api.write.reports | forbidden |
| alle | /api/organization/smtp, /api/organization/whitelabel/**, /api/organization/sso/** | admin. Für Tokens mit Scopes gesperrt: nimm ein Token ohne Scopes. | - | forbidden, ssoAdminOnly, apiTokenScopeForbidden |
Benachrichtigungskanäle
| Methode | Pfad | Wer darf aufrufen | Scope | Abweisung mit |
|---|---|---|---|---|
GET | /api/notification-channels, /api/notification-channels/:id | Jede Rolle; eingeschränkte Aufrufer sehen die Kanäle ihrer Kunden und die Organisationskanäle | api.read.alerts | forbidden |
POST, PATCH, DELETE | /api/notification-channels, /api/notification-channels/:id | Organisationskanäle: admin. Kundenkanäle: admin, oder readonly innerhalb seines Kundenbereichs. editor kann Kanäle nicht ändern. | api.write.alerts | forbidden |
Statusseiten
Das Statusseiten-Modul muss aktiv sein. Kundengebundene Aufrufer erreichen nur Seiten ihrer Kunden; eine Seite ohne Kunde braucht organisationsweiten Zugriff (403 forbidden).
| Methode | Pfad | Wer darf aufrufen | Scope | Abweisung mit |
|---|---|---|---|---|
GET | /api/status-pages, /api/status-pages/:id, …/components, …/groups, /api/status-pages/maintenances/:id, /api/status-pages/domains/:id | admin, editor, readonly | api.read.statuspages | forbidden, 404 statusPageNotFound |
POST, PATCH, DELETE | /api/status-pages, /api/status-pages/:id, Komponenten, Gruppen, Wartungen, POST /api/status-pages/domains, DELETE /api/status-pages/domains/:id | admin, editor; kundengebundene Nutzer und Tokens (auch readonly) nur self_service-Seiten ihrer Kunden | api.write.statuspages | forbidden, statusPageLimitReached, managed_by_organization |
GET, PATCH | /api/status-pages/:id/design | admin, editor, readonly | api.read.statuspages / api.write.statuspages | forbidden |
POST | /api/status-pages/domains/verify, /api/status-pages/domains/activate | admin | api.write.statuspages | forbidden |
Incident Management
Incident Management muss für die Organisation aktiviert sein (403 imNotEnabled; /api/im/org-settings lesen und ändern geht auch ohne). Es braucht die Rolle admin, editor oder responder ohne Kundenzuordnung; readonly und kundengebundene Tokens bekommen 403 imAccessDenied oder 403 customerScopedTokenForbidden. Agent-Tokens können Incident Management nicht nutzen. Scopes: api.read.incidents für GET, api.write.incidents für jede andere Methode.
| Methode | Pfad | Wer darf aufrufen | Abweisung mit |
|---|---|---|---|
GET | jeder /api/im/**-Pfad unten außer den zwei Admin-Pfaden | Jede IM-Rolle (admin, editor, responder) | imAccessDenied |
POST, PATCH, DELETE | /api/im/teams/:id/** (Mitglieder, Einladung, Stufen, Eskalationen, Vertretungen), /api/im/schedules/**, /api/im/tiers/:id/schedules, /api/im/sources/**, /api/im/routing/**, /api/im/statuspage-rules/** | admin, oder ein Team-Admin (imRole: admin) dieses Teams. Einen neuen Nutzer einladen braucht admin. | imTeamWriteDenied, forbidden |
POST | /api/im/teams | admin | imTeamWriteDenied |
POST, PATCH, DELETE | /api/im/channels, /api/im/channels/:id | Organisationskanal: admin. Teamkanal: admin oder Team-Admin. | imChannelWriteDenied |
POST, PATCH, DELETE | /api/im/outbound, /api/im/outbound/:id | Organisations-Integration: admin. Team-Integration: admin oder Team-Admin. | imOutboundWriteDenied, imTeamWriteDenied |
PATCH | /api/im/org-settings | admin | forbidden |
GET, PUT | /api/im/notification-template, /api/im/users/:id/notification-settings | admin, auch zum Lesen | forbidden |
Ein API-Token ist nie Team-Admin: Team-Admin-Rechte gehören einem Nutzer. Team-Ressourcen mit einem Token zu ändern braucht deshalb ein Token, das ein admin angelegt hat.