Eine Organisation aktualisieren

PATCH /fapi/v1/organizations/{org_id} · wird vom Anmeldehost der Umgebung aufgerufen

Ändert den Namen, den Slug oder die Markenfarbe einer Organisation (JSON Merge Patch, RFC 7396). Metadaten, die externe ID und das Mitgliederlimit können hier nicht geändert werden. Erfordert das Cookie __Host-idp_session des angemeldeten Benutzers; fehlt das Cookie, ist es abgelaufen oder widerrufen, wird 401 unauthenticated zurückgegeben. Eine Erstanbieter-Anwendung auf einem anderen Ursprung kann stattdessen ihr Front-API-Zugriffstoken senden (Authorization: DPoP <token> mit einem DPoP-Proof; siehe Front-API-Zugriffstoken). Der Benutzer muss aktives Mitglied der Organisation sein und die Berechtigung idp_org:update besitzen. Ein Benutzer, der kein Mitglied ist, erhält 404 not_found; ein Mitglied ohne die Berechtigung erhält 403 insufficient_permissions.

Mit @keenauth/js: await keenauth.organizations.update(orgId, { name: "Acme Inc" }, { expectedVersion: 4 }).

Anfrage

Header:

Header Pflicht Beschreibung
Idp-Client ja SDK-Kennung.
Origin ja, mit dem Cookie Muss genau https://<Anmeldehost> sein.
Content-Type ja application/json oder application/merge-patch+json.
If-Match nein "<version>" der Organisation, wie zuletzt gelesen; wurde sie seitdem geändert, wird 412 precondition_failed zurückgegeben und nichts geändert.

org_id: die Organisations-ID (org_…).

Body (mindestens ein Feld):

Feld Pflicht Beschreibung
name nein Neuer Anzeigename; darf nicht null sein.
slug nein Neuer Slug; darf nicht null sein. Der alte Slug bleibt 90 Tage reserviert, und ein Slug kann innerhalb von 30 Tagen einmal geändert werden.
brand_color nein #RRGGBB; null entfernt die Farbe.

Antwort

200 OK mit einem neuen ETag; der Body ist die Organisation (siehe Eine Organisation abrufen).

Fehler

Status Code Wann
400 unknown_field Der Body enthält ein anderes Feld als name, slug und brand_color.
401 unauthenticated Kein gültiges Sitzungs-Cookie.
403 origin_not_allowed Origin fehlt oder ist falsch.
403 insufficient_permissions Der Benutzer hat idp_org:update in der Organisation nicht.
404 not_found Keine solche Organisation für diesen Benutzer; eine unbekannte, fehlerhafte oder fremde ID führt zur selben Antwort.
409 slug_taken Eine andere Organisation verwendet den Slug.
409 slug_reserved Der Slug ist in der 90-tägigen Reservierung einer anderen Organisation.
409 slug_change_rate_limited Der Slug wurde in den letzten 30 Tagen bereits geändert.
409 organization_disabled Die Organisation ist deaktiviert.
409 organization_pending_deletion Die Organisation ist zur Löschung vorgesehen.
412 precondition_failed If-Match nennt nicht die aktuelle Version, oder die Organisation wurde während der Verarbeitung der Anfrage geändert.
422 validation_failed Ein Feld ist ungültig oder an einer Stelle null, wo das nicht erlaubt ist, oder der Patch ist leer (empty_patch).
503 service_unavailable Vorübergehend nicht verfügbar; erneut versuchen nach Retry-After.

Beispiel

curl -X PATCH https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "4"' \
  -b cookies.txt \
  -d '{"name": "Acme Inc", "brand_color": null}'

Die Antwort hat dieselbe Struktur wie Eine Organisation abrufen, mit "version": 5.