Eine Organisation aktualisieren

PATCH /v1/organizations/{org_id} · Berechtigung organizations:write

Aktualisiert eine Organisation mit einem JSON-Merge-Patch (RFC 7396, Content-Type: application/merge-patch+json). Nicht gesendete Felder bleiben unverändert; ein Patch, der nichts ändert, erhöht die Version nicht. name und slug können nicht geleert werden.

Anfrage

Feld Typ Pflicht Beschreibung
org_id path ja Organisations-ID (org_…).
If-Match header ja Pflicht. Das ETag des letzten Lesevorgangs ("<version>").
name string nein Anzeigename, 1-256 Zeichen, keine Steuerzeichen.
slug string nein Neuer Slug (gleiches Format). Kann einmal alle 30 Tage geändert werden; der alte Slug bleibt 90 Tage reserviert.
external_id string | null nein Ihre eigene Kennung, bis zu 255 Zeichen; in der Umgebung eindeutig. null entfernt sie.
metadata object | null nein Wird mit dem aktuellen Objekt zusammengeführt (RFC 7396): Ein auf null gesetztes Mitglied wird entfernt; null für das gesamte Feld setzt es auf {} zurück.
brand_color string | null nein Markenfarbe #RRGGBB; wird in Großbuchstaben gespeichert. null entfernt sie.
max_memberships integer | null nein Obergrenze für Mitgliedschaften, mindestens 1; null bedeutet unbegrenzt.
default_zoneinfo string | null nein Standard-IANA-Zeitzone (zum Beispiel Europe/Istanbul), die bei Registrierung, Einladung, JIT-SSO und SCIM im Organisationskontext verwendet wird, wenn Browser oder Identitätsanbieter keine liefern. null entfernt sie (es gilt der Umgebungsstandard).

Anfragekörper:

{
  "name": "Acme Corporation",
  "metadata": {
    "tier": null,
    "region": "eu"
  }
}

Antwort

200 OK mit der aktualisierten Organisation und ihrem neuen ETag.

{
  "id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "name": "Acme Corporation",
  "slug": "acme",
  "external_id": "crm-4821",
  "status": "active",
  "metadata": {
    "region": "eu"
  },
  "brand_color": "#1F6FEB",
  "max_memberships": null,
  "default_zoneinfo": null,
  "created_via": "admin_api",
  "disabled_at": null,
  "deletion_requested_at": null,
  "deletion_due_at": null,
  "created_at": "2026-10-12T09:30:00.123456Z",
  "updated_at": "2026-10-12T10:05:00.654321Z",
  "version": 2
}

Fehler

HTTP code Wann
400 unknown_field Der Anfragekörper enthält ein Feld, das nicht im Schema steht oder schreibgeschützt ist (id, status …).
401 unauthenticated Der Berechtigungsnachweis fehlt, ist ungültig oder wurde widerrufen.
403 insufficient_permissions Der Berechtigungsnachweis hat nicht die erforderliche Berechtigung.
404 not_found In dieser Umgebung existiert keine Organisation mit dieser ID.
409 slug_taken Der Slug wird bereits von einer anderen Organisation verwendet.
409 slug_reserved Der Slug ist ein reserviertes Wort oder der frühere Slug einer anderen Organisation (90 Tage reserviert).
409 slug_change_rate_limited Der Slug wurde vor weniger als 30 Tagen geändert.
409 external_id_taken Die external_id wird bereits von einer anderen Organisation verwendet.
409 organization_pending_deletion Die Organisation wartet auf die Selbstbedienungslöschung; brechen Sie zuerst die Löschung ab.
412 precondition_failed If-Match stimmt nicht mit der aktuellen Version überein; lesen Sie die Organisation erneut.
422 validation_failed Ein Feld ist ungültig (name, slug, external_id, metadata, brand_color, max_memberships, default_zoneinfo).
428 precondition_required If-Match fehlt.
429 rate_limited Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach der Zeit aus Retry-After.
503 service_unavailable Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach der Zeit aus Retry-After.

Beispiel

curl -X PATCH "https://api.eu.keenauth.com/v1/organizations/org_01j9xk3m7q8r2s4t6v8w0y2z4a" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "1"' \
  -d '{"name":"Acme Corporation"}'