---
title: "Berechtigungen je Endpunkt"
description: "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:

1. **Anmeldung.** Kein Token, oder ein widerrufenes, abgelaufenes oder vertipptes: `401 unauthorized`.
2. **Token-Art.** Ein kundengebundenes Token auf einem organisationsweiten Pfad: `403 customerScopedTokenForbidden`. Ein Token mit Scopes, dem der Scope des Pfads fehlt: `403 apiTokenScopeForbidden`. Meldung und `data.requiredScope` nennen den fehlenden Scope, zum Beispiel `api.write.monitors`. Siehe [Token-Scopes](/api/introduction/token-scopes-organization-vs-customer).
3. **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 als `readonly`. Alte Tokens ohne hinterlegten Aussteller handeln als `admin`. Eine nicht zugelassene Rolle bekommt `403` mit dem Code aus der Tabelle unten.
4. **Kundenbereich.** `readonly`-Nutzer, Editoren mit Kundenzuordnung und kundengebundene Tokens erreichen nur ihre eigenen Kunden. Eine einzelne Ressource außerhalb dieses Bereichs antwortet mit `404` und dem Nicht-gefunden-Code der Ressource, nie mit `403`. 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.
5. **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.