Organisation aktualisieren

PATCH /api/organization

Anfrage (Request Body)

{
  "name": "Neuer Name",
  "companyName": "Neuer Firmenname",
  "street": "Neue Straße",
  "postalCode": "54321",
  "city": "Neue Stadt",
  "country": "US",
  "vatId": "US123",
  "countryCode": "AT",
  "billingEmail": "neu@deinkunde.com",
  "requireMfaAdmins": true,
  "requireMfaEditors": false,
  "requireMfaReadonly": false,
  "requireMfaCustomers": false,
  "defaultNotificationChannels": {
    "email": true,
    "sms": false,
    "webhook": true,
    "integrations": false
  },
  "defaultNotificationTargets": {
    "email": "both", // customer, organization, both
    "sms": "organization",
    "webhook": "organization",
    "integrations": "customer"
  }
}

Beispiel (cURL)

BASE_URL="https://uptimeify.io"
TOKEN="<dein-api-token>"

curl -X PATCH "$BASE_URL/api/organization" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Neuer Name",
    "billingEmail": "neu@deinkunde.com"
  }'

Hinweise:

• Die Organisation wird automatisch aus deiner authentifizierten Session bzw. deinem API-Token abgeleitet.

• Die Legacy-Route PATCH /api/organizations/:organizationPublicId bleibt aus Kompatibilitätsgründen weiterhin verfügbar.

• Der plurale org-lose Alias PATCH /api/organizations wird ebenfalls unterstützt.

• Global Admins brauchen für die org-lose Route einen aktiven Organisationskontext in der Session.

• countryCode ist das Abrechnungsland der Organisation als ISO-3166-1-Alpha-2-Code (zwei Buchstaben, bei der Eingabe unabhängig von Groß-/Kleinschreibung, gespeichert und zurückgegeben immer in Großbuchstaben). Er bestimmt die umsatzsteuerliche Behandlung: Reverse Charge nach AGB § 10.2 setzt voraus, dass hier ein EU-Mitgliedsstaat außer Deutschland steht.

• Das Setzen von vatId oder countryCode (eines der beiden, egal ob in derselben Anfrage oder getrennt) setzt vatIdStatus auf unverified zurück. Ein vorheriges valid-Ergebnis überlebt eine Änderung an keinem der beiden Felder, validiere nach der Änderung erneut mit USt-IdNr. validieren, um die Reverse-Charge-Berechtigung wiederherzustellen.

• Kontingent-Änderungen sind nicht symmetrisch. Eine Änderung mit höherem quotaMonthlyPriceCents als bisher wird sofort wirksam; der Differenzbetrag wird anteilig für den Rest des laufenden Abrechnungszeitraums berechnet. Eine Änderung mit niedrigerem Preis wird nicht sofort wirksam: Nach AGB § 10.5 wird sie zum Ende des laufenden Abrechnungszeitraums geplant, und für den nicht genutzten Teil des höheren Plans gibt es keine Rückvergütung. Bis dahin behält die Organisation ihren aktuellen Tarif, und alle Kontingent-Felder der Organisation beschreiben weiterhin diesen Tarif. Die Richtung entscheidet allein der Preis, nie das Monitor-Limit. Ein Tarif, der bei mehr Monitoren weniger kostet, ist also trotzdem eine Reduzierung.

• Eine geplante Reduzierung wird als pendingQuotaChange zurückgegeben, hier wie bei Organisations-Details abrufen; ohne geplante Änderung ist das Feld null. Pro Organisation gibt es höchstens eine geplante Änderung: Eine zweite Reduzierung ersetzt die erste, eine Erhöhung hebt sie auf (sonst würdest du an der Periodengrenze stillschweigend wieder heruntergestuft). Zum Abbrechen ohne Tarifwechsel dient Geplante Kontingent-Änderung abbrechen, denselben Tarif hier erneut zu senden gilt als unverändert und bewirkt nichts.

• Eine Reduzierung unter die aktuelle Monitor-Nutzung der Organisation wird sofort mit 400 abgelehnt. Dieselbe Prüfung läuft erneut, wenn die Änderung angewendet wird: Ist die Organisation inzwischen über das neue Limit gewachsen, wird die Reduzierung verworfen statt angewendet, die Organisation behält den höheren Tarif.

• requireMfaAdmins, requireMfaEditors, requireMfaReadonly und requireMfaCustomers (jeweils boolean) erzwingen unabhängig voneinander die Zwei-Schritt-Bestätigung für vier unterschiedliche Zielgruppen, setze eine beliebige Teilmenge der vier, um MFA schrittweise auszurollen. Die Zielgruppe eines Nutzers ist NICHT einfach seine Rolle. Jeder Nutzer in der Organisation ist entweder ein Team-Mitglied oder ein Kundennutzer:

  • Team-Mitglied: ein admin, oder ein editor/readonly-Mitglied ohne explizite Kundenzuordnung (keine Zeile in user_customer_access).
  • Kundennutzer: ein editor oder readonly-Mitglied, das einem oder mehreren bestimmten Kunden zugeordnet ist (mindestens eine Zeile in user_customer_access), unabhängig von der Rolle.

  requireMfaAdmins, requireMfaEditors und requireMfaReadonly gelten NUR für Team-Mitglieder, ein Editor oder Readonly-Mitglied, das bestimmten Kunden zugeordnet ist, wird von requireMfaEditors/requireMfaReadonly NICHT erfasst, selbst wenn dieser Schalter aktiv ist. requireMfaCustomers erfasst stattdessen jeden Kundennutzer, unabhängig von der Rolle. Ein Admin ist nie einzelnen Kunden zugeordnet (Admins haben immer uneingeschränkten Zugriff), daher greift requireMfaCustomers bei einem Admin nie, nur requireMfaAdmins kann einen Admin je zur Zwei-Schritt-Bestätigung zwingen.

  Die plattformweite Durchsetzung für Platform Admins/Supporter ist ein separates, nur vom Betreiber steuerbares Environment-Flag (MFA_ENFORCE_PLATFORM_ADMINS, standardmäßig aus) und wird von diesen Feldern nicht berührt. Jedes der vier Felder kann von einem Organisations-Admin gesetzt werden, nicht nur von einem Global Admin, aber nur aus einer echten, eingeloggten Benutzer-Session heraus. Eine Anfrage, deren Body requireMfaAdmins, requireMfaEditors, requireMfaReadonly oder requireMfaCustomers enthält, wird mit 403 nonUserSessionForbidden abgelehnt, wenn sie mit einem API-Token oder Agent-Access-Token erfolgt, selbst mit einem organisations-gescopten Token mit Admin-Rechten. Sonst könnte ein geleaktes Token den MFA-Schutz der Organisation im Alleingang aushebeln.

• Das Ändern von einem beliebigen der vier Felder, in beide Richtungen (an oder aus), wird mit 400 mfaRequiredForActor abgelehnt, solange der ausführende Admin auf dem eigenen Konto keine Zwei-Schritt-Bestätigung aktiviert hat. Das Aktivieren ohne eigenen Faktor würde dich sofort aus der eigenen Organisation aussperren (sofern der Schalter die eigene Zielgruppe betrifft); das Deaktivieren ist auf dieselbe Weise abgesichert, damit ein erzwungener, aber nicht eingerichteter Admin diese Felder nicht nutzen kann, um sich der eigenen MFA-Pflicht der Organisation zu entziehen.

Häufige Fehler

• 400 Invalid request body wenn der Payload nicht zum Schema passt
• 400 Organization ID is required in the authenticated session wenn aus Session/Token keine Organisation abgeleitet werden kann
• 400 mfaRequiredForActor wenn requireMfaAdmins, requireMfaEditors, requireMfaReadonly oder requireMfaCustomers (egal welches, egal ob true oder false) gesetzt wird, während das eigene Konto des Aufrufers keine Zwei-Schritt-Bestätigung aktiviert hat
• 403 nonUserSessionForbidden wenn der Request Body requireMfaAdmins, requireMfaEditors, requireMfaReadonly oder requireMfaCustomers enthält und der Aufrufer ein API-Token oder Agent-Access-Token statt einer echten Benutzer-Session ist
• 401 Unauthorized wenn du nicht angemeldet bist
• 403 Forbidden wenn du keine Admin-Berechtigung zum Aktualisieren der Organisation hast

Antwort (Response)

Gibt das aktualisierte Organisationsobjekt zurück, dazu pendingQuotaChange mit der Reduzierung, die diese Anfrage geplant hat:

{
  "pendingQuotaChange": {
    "effectiveAt": "2026-08-01T00:00:00.000Z",
    "quotaWebsitesLimit": 25,
    "quotaMonthlyPriceCents": 6900
  }
}

pendingQuotaChange ist null, wenn die Anfrage nichts geplant hat, auch dann, wenn sie eine Erhöhung sofort angewendet hat. effectiveAt ist der erste Zeitpunkt, ab dem der neue Tarif gilt: bei monatlicher Abrechnung der nächste UTC-Monatsanfang, bei jährlicher das Ende der bezahlten Laufzeit.

Siehe Fehlerliste für Fehlerantworten.