Ein Verzeichnis aktualisieren

PATCH /v1/directories/{directory_id} · Berechtigung directories:write

Aktualisiert den Namen des Verzeichnisses und seine Provisionierungseinstellungen mit einem JSON-Merge-Patch (RFC 7396, Content-Type: application/merge-patch+json). If-Match ist erforderlich; der aktuelle Wert ist der ETag-Header von GET /v1/directories/{directory_id}. Kein Feld akzeptiert null. Ein Patch, der nichts ändert, schreibt nichts und behält die Version bei. Der Schreibvorgang wird als directory.updated protokolliert, mit altem und neuem Wert jeder geänderten Einstellung.

provisioning_mode kann nicht geändert werden, solange das Verzeichnis nicht gelöschte Benutzerdatensätze enthält (409 conflict); löschen Sie das Verzeichnis und legen Sie es stattdessen neu an.
attribute_allowlist wird als Ganzes ersetzt. Ein aus der Liste entferntes Attribut wird in derselben Transaktion aus den Benutzerdatensätzen des Verzeichnisses gelöscht.
mass_deprovision_guard kann teilweise gepatcht werden; nicht angegebene Unterfelder bleiben erhalten.

Anfrage

Feld	Typ	Pflicht	Beschreibung
`directory_id`	Pfad	ja	SCIM-Verzeichnis-ID (`dir_…`).
`If-Match`	Header	ja	Aktueller `ETag` des Verzeichnisses.
`name`	Zeichenkette	nein	1–64 Zeichen, keine Steuerzeichen, keine führenden oder nachgestellten Leerzeichen.
`provisioning_mode`	Zeichenkette	nein	`user_store` (Umgebungsbenutzer, Organisationsmitgliedschaften und Gruppenrollen werden ebenfalls geschrieben) oder `mirror` (nur die Verzeichnisdatensätze werden behalten).
`attribute_allowlist`	Array	nein	Optionale SCIM-Attribute, die gespeichert werden, ohne Duplikate: `title`, `usertype`, `phonenumbers` sowie die Enterprise-Erweiterung `employeenumber`, `department`, `division`, `costcenter`, `organization`, `manager` (vollständige Namen `urn:ietf:params:scim:schemas:extension:enterprise:2.0:user:`).
`unverified_domain_action`	Zeichenkette	nein	Ein Benutzer, dessen E-Mail-Domain nicht verifiziert ist: `invite` (eingeladene Mitgliedschaft) oder `mirror_only` (nur Verzeichnisdatensatz).
`delete_action`	Zeichenkette	nein	SCIM `DELETE /Users`: `remove_membership` oder `delete_user` (löscht den vom Verzeichnis verwalteten Benutzer).
`on_delete_memberships`	Zeichenkette	nein	Was mit den Mitgliedschaften aus diesem Verzeichnis geschieht, wenn das Verzeichnis gelöscht wird: `keep`, `suspend` oder `remove`.
`mass_deprovision_guard`	Objekt	nein	`enabled` (Boolescher Wert), `percent` (5–50) und `absolute_min` (10–1000): Deprovisionierungen, die beide Schwellen innerhalb von 5 Minuten überschreiten, werden zur Genehmigung zurückgehalten.
`send_welcome_email`	Boolescher Wert	nein	Ob ein neuer Verzeichnisbenutzer eine E-Mail zur Kontoaktivierung erhält.

Antwort

200 OK mit dem Verzeichnis und seinem neuen ETag.

{
  "id": "dir_01j9xm2n4p6q8r0s2t4v6w8y0z",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "type": "scim",
  "name": "Okta EU",
  "state": "active",
  "base_url": "https://acme.eu.keenauth.app/scim/v2/dir_01j9xm2n4p6q8r0s2t4v6w8y0z",
  "created_at": "2026-10-19T09:31:00.123456Z",
  "last_request_at": null,
  "provisioning_mode": "user_store",
  "attribute_allowlist": ["title", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:user:department"],
  "unverified_domain_action": "invite",
  "delete_action": "remove_membership",
  "on_delete_memberships": "keep",
  "mass_deprovision_guard": {"enabled": true, "percent": 20, "absolute_min": 25},
  "send_welcome_email": false
}

Fehler

HTTP	code	Wann
400	`malformed_request`	Der Body ist kein JSON-Objekt.
400	`unknown_field`	Der Patch enthält ein Feld, das nicht geschrieben werden kann (zum Beispiel `state`).
404	`not_found`	Das Verzeichnis existiert in dieser Umgebung nicht.
409	`conflict`	`provisioning_mode` wird geändert, während das Verzeichnis Benutzerdatensätze enthält, oder das Verzeichnis wird gerade gelöscht.
412	`precondition_failed`	`If-Match` stimmt nicht mit der aktuellen Version überein.
415	`unsupported_media_type`	`Content-Type` ist nicht `application/merge-patch+json`.
422	`validation_failed`	Ein Feld ist `null` oder ungültig; der Fehler nennt das Feld (zum Beispiel `/mass_deprovision_guard/percent` `invalid`).
428	`precondition_required`	`If-Match` fehlt.
401	`unauthenticated`	Die Anmeldeinformation fehlt, ist ungültig oder widerrufen.
403	`insufficient_permissions`	Die Anmeldeinformation besitzt nicht die erforderliche Berechtigung.
429	`rate_limited`	Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach der Zeit aus `Retry-After`.
503	`service_unavailable`	Die Verzeichnissynchronisation ist vorübergehend nicht verfügbar oder in dieser Bereitstellung nicht konfiguriert; wiederholen Sie die Anfrage nach der Zeit aus `Retry-After`.

Beispiel

curl -i -X PATCH "https://api.eu.keenauth.com/v1/directories/dir_01j9xm2n4p6q8r0s2t4v6w8y0z" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H 'If-Match: "3"' \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"name":"Okta EU","mass_deprovision_guard":{"percent":20}}'