Aggiorna un'organizzazione

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

Aggiorna un'organizzazione con una merge patch JSON (RFC 7396, Content-Type: application/merge-patch+json). I campi non inviati non cambiano; una patch che non modifica nulla non cambia la versione. name e slug non possono essere cancellati.

Richiesta

Campo Tipo Obbligatorio Descrizione
org_id path sì ID dell'organizzazione (org_…).
If-Match header sì Obbligatorio. Il ETag dell'ultima lettura ("<version>").
name string no Nome visualizzato, da 1 a 256 caratteri, senza caratteri di controllo.
slug string no Nuovo slug (stesso formato). Può cambiare una volta ogni 30 giorni; il vecchio slug resta riservato per 90 giorni.
external_id string | null no Il tuo identificatore, fino a 255 caratteri; univoco nell'ambiente. null lo cancella.
metadata object | null no Unito all'oggetto attuale (RFC 7396): un membro impostato a null viene rimosso; null per l'intero campo lo reimposta a {}.
brand_color string | null no Colore del brand #RRGGBB; salvato in maiuscolo. null lo cancella.
max_memberships integer | null no Limite di appartenenze, almeno 1; null significa illimitato.
default_zoneinfo string | null no Fuso orario IANA predefinito (per esempio Europe/Istanbul), usato per iscrizione, inviti, JIT SSO e SCIM nel contesto dell'organizzazione quando il browser o l'IdP non ne forniscono uno. null lo cancella (si applica il predefinito dell'ambiente).

Corpo della richiesta:

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

Risposta

200 OK con l'organizzazione aggiornata e il suo nuovo 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
}

Errori

HTTP codice Quando
400 unknown_field Il corpo contiene un campo che non è nello schema o è di sola lettura (id, status…).
401 unauthenticated La credenziale manca, non è valida o è stata revocata.
403 insufficient_permissions La credenziale non ha l'autorizzazione richiesta.
404 not_found Non esiste un'organizzazione con questo ID in questo ambiente.
409 slug_taken Lo slug è usato da un'altra organizzazione.
409 slug_reserved Lo slug è una parola riservata o il vecchio slug di un'altra organizzazione (riservato per 90 giorni).
409 slug_change_rate_limited Lo slug è stato cambiato meno di 30 giorni fa.
409 external_id_taken Il external_id è usato da un'altra organizzazione.
409 organization_pending_deletion L'organizzazione è in attesa di eliminazione self-service; annulla prima l'eliminazione.
412 precondition_failed If-Match non corrisponde alla versione attuale; leggi di nuovo l'organizzazione.
422 validation_failed Un campo non è valido (name, slug, external_id, metadata, brand_color, max_memberships, default_zoneinfo).
428 precondition_required If-Match manca.
429 rate_limited È stato superato il limite di richieste; riprova dopo il periodo indicato in Retry-After.
503 service_unavailable Una dipendenza non è temporaneamente disponibile; riprova dopo il periodo indicato in Retry-After.

Esempio

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