Mettre à jour une organisation

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

Met à jour une organisation avec un JSON merge patch (RFC 7396, Content-Type: application/merge-patch+json). Les champs non envoyés ne changent pas ; un patch qui ne modifie rien ne change pas la version. name et slug ne peuvent pas être effacés.

Requête

Champ Type Obligatoire Description
org_id path oui Identifiant de l'organisation (org_…).
If-Match header oui Obligatoire. L'ETag de la dernière lecture ("<version>").
name string non Nom d'affichage, de 1 à 256 caractères, sans caractères de contrôle.
slug string non Nouveau slug (même format). Peut être modifié une fois tous les 30 jours ; l'ancien slug reste réservé pendant 90 jours.
external_id string | null non Votre propre identifiant, jusqu'à 255 caractères ; unique dans l'environnement. null l'efface.
metadata object | null non Fusionné avec l'objet actuel (RFC 7396) : un membre défini à null est supprimé ; null pour l'ensemble du champ le réinitialise à {}.
brand_color string | null non Couleur de marque #RRGGBB ; enregistrée en majuscules. null l'efface.
max_memberships integer | null non Plafond de membres, au moins 1 ; null signifie illimité.
default_zoneinfo string | null non Fuseau horaire IANA par défaut (par exemple Europe/Istanbul), utilisé pour l'inscription, l'invitation, le SSO JIT et SCIM dans le contexte de l'organisation lorsque le navigateur ou le fournisseur d'identité n'en fournit aucun. null l'efface (la valeur par défaut de l'environnement s'applique).

Corps de la requête :

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

Réponse

200 OK avec l'organisation mise à jour et son nouvel 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
}

Erreurs

HTTP code Quand
400 unknown_field Le corps contient un champ absent du schéma ou en lecture seule (id, status…).
401 unauthenticated L'identifiant est absent, invalide ou révoqué.
403 insufficient_permissions L'identifiant ne dispose pas de l'autorisation requise.
404 not_found Aucune organisation avec cet identifiant n'existe dans cet environnement.
409 slug_taken Le slug est utilisé par une autre organisation.
409 slug_reserved Le slug est un mot réservé ou l'ancien slug d'une autre organisation (réservé pendant 90 jours).
409 slug_change_rate_limited Le slug a été modifié il y a moins de 30 jours.
409 external_id_taken Le external_id est utilisé par une autre organisation.
409 organization_pending_deletion L'organisation attend une suppression en libre-service ; annulez d'abord la suppression.
412 precondition_failed If-Match ne correspond pas à la version actuelle ; relisez l'organisation.
422 validation_failed Un champ est invalide (name, slug, external_id, metadata, brand_color, max_memberships, default_zoneinfo).
428 precondition_required If-Match est absent.
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 Une dépendance est temporairement indisponible ; réessayez après la durée indiquée par Retry-After.

Exemple

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