Mettre à jour un annuaire

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

Met à jour le nom de l'annuaire et ses paramètres de provisionnement avec un JSON merge patch (RFC 7396, Content-Type: application/merge-patch+json). If-Match est obligatoire ; la valeur actuelle est l'en-tête ETag de GET /v1/directories/{directory_id}. Aucun champ n'accepte null. Un patch qui ne modifie rien n'écrit rien et conserve la version. L'écriture est auditée sous directory.updated, avec l'ancienne et la nouvelle valeur de chaque paramètre modifié.

provisioning_mode ne peut pas changer tant que l'annuaire contient des enregistrements d'utilisateurs non supprimés (409 conflict) ; supprimez l'annuaire et recréez-le à la place.
attribute_allowlist est remplacée en totalité. Un attribut retiré de la liste est supprimé des enregistrements d'utilisateurs de l'annuaire dans la même transaction.
mass_deprovision_guard peut être mis à jour partiellement ; les sous-champs omis sont conservés.

Requête

Champ	Type	Obligatoire	Description
`directory_id`	chemin	oui	ID de l'annuaire SCIM (`dir_…`).
`If-Match`	en-tête	oui	`ETag` actuel de l'annuaire.
`name`	chaîne	non	1 à 64 caractères, sans caractères de contrôle, sans espace en début ou en fin.
`provisioning_mode`	chaîne	non	`user_store` (les utilisateurs de l'environnement, les appartenances à l'organisation et les rôles de groupe sont aussi écrits) ou `mirror` (seuls les enregistrements de l'annuaire sont conservés).
`attribute_allowlist`	tableau	non	Attributs SCIM facultatifs à stocker, sans doublons : `title`, `usertype`, `phonenumbers` et les attributs de l'extension entreprise `employeenumber`, `department`, `division`, `costcenter`, `organization`, `manager` (noms complets `urn:ietf:params:scim:schemas:extension:enterprise:2.0:user:`).
`unverified_domain_action`	chaîne	non	Utilisateur dont le domaine e-mail n'est pas vérifié : `invite` (appartenance invitée) ou `mirror_only` (enregistrement de l'annuaire seulement).
`delete_action`	chaîne	non	SCIM `DELETE /Users` : `remove_membership` ou `delete_user` (supprime l'utilisateur géré par l'annuaire).
`on_delete_memberships`	chaîne	non	Sort des appartenances issues de cet annuaire lorsque l'annuaire est supprimé : `keep`, `suspend` ou `remove`.
`mass_deprovision_guard`	objet	non	`enabled` (booléen), `percent` (5–50) et `absolute_min` (10–1000) : les désactivations qui dépassent les deux seuils en 5 minutes sont retenues pour approbation.
`send_welcome_email`	booléen	non	Indique si un nouvel utilisateur de l'annuaire reçoit un e-mail d'activation du compte.

Réponse

200 OK avec l'annuaire et son nouvel 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
}

Erreurs

HTTP	code	Quand
400	`malformed_request`	Le corps n'est pas un objet JSON.
400	`unknown_field`	Le patch contient un champ qui ne peut pas être écrit (par exemple `state`).
404	`not_found`	L'annuaire n'existe pas dans cet environnement.
409	`conflict`	`provisioning_mode` change alors que l'annuaire contient des enregistrements d'utilisateurs, ou que l'annuaire est en cours de suppression.
412	`precondition_failed`	`If-Match` ne correspond pas à la version actuelle.
415	`unsupported_media_type`	`Content-Type` n'est pas `application/merge-patch+json`.
422	`validation_failed`	Un champ est `null` ou invalide ; l'erreur nomme le champ (par exemple `/mass_deprovision_guard/percent` `invalid`).
428	`precondition_required`	`If-Match` est absent.
401	`unauthenticated`	L'identifiant est absent, invalide ou révoqué.
403	`insufficient_permissions`	L'identifiant n'a pas l'autorisation requise.
429	`rate_limited`	La limite de débit a été dépassée ; réessayez après la durée indiquée par `Retry-After`.
503	`service_unavailable`	La synchronisation des annuaires est temporairement indisponible ou non configurée dans ce déploiement ; réessayez après la durée indiquée par `Retry-After`.

Exemple

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}}'