Creare un'organizzazione

POST /v1/organizations · autorizzazione organizations:write

Crea un'organizzazione nell'ambiente. La risposta contiene un ETag. Viene pubblicato un evento organization.created e la modifica viene registrata nel log di audit della gestione.

Richiesta

Campo Tipo Obbligatorio Descrizione
Idempotency-Key header no Facoltativo. 16-64 caratteri [A-Za-z0-9_-]; ripetere la stessa chiave con la stessa richiesta restituisce la stessa risposta.
name string sì Nome visualizzato, da 1 a 256 caratteri, senza caratteri di controllo.
slug string no Da 3 a 64 caratteri a-z, 0-9 e trattini singoli; univoco nell'ambiente. Derivato dal nome se omesso.
external_id string | null no Il tuo identificativo, fino a 255 caratteri; univoco nell'ambiente. null lo rimuove.
metadata object | null no Oggetto JSON, al massimo 16 KiB, 5 livelli e 100 chiavi di primo livello. Restituito solo dall'API di gestione.
brand_color string | null no Colore del brand #RRGGBB; salvato in maiuscolo. null lo rimuove.
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 rimuove (si applica il valore predefinito dell'ambiente).

Corpo della richiesta:

{
  "name": "Acme Corp",
  "slug": "acme",
  "external_id": "crm-4821",
  "metadata": {
    "tier": "gold"
  },
  "brand_color": "#1F6FEB"
}

Risposta

201 Created con la nuova organizzazione.

{
  "id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "name": "Acme Corp",
  "slug": "acme",
  "external_id": "crm-4821",
  "status": "active",
  "metadata": {
    "tier": "gold"
  },
  "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-12T09:30:00.123456Z",
  "version": 1
}

Errori

HTTP code Quando
400 unknown_field Il corpo contiene un campo che non è nello schema oppure è di sola lettura (id, status…).
401 unauthenticated Le credenziali sono mancanti, non valide o revocate.
403 insufficient_permissions Le credenziali non hanno l'autorizzazione richiesta.
403 quota_exceeded È stato raggiunto il limite di organizzazioni del piano dell'ambiente (organizations_per_environment_max).
409 slug_taken Lo slug è usato da un'altra organizzazione.
409 slug_reserved Lo slug è una parola riservata oppure lo slug precedente di un'altra organizzazione (riservato per 90 giorni).
409 external_id_taken Il external_id è usato da un'altra organizzazione.
422 validation_failed Un campo non è valido (name, slug, external_id, metadata, brand_color, max_memberships, default_zoneinfo).
422 idempotency_key_reuse La Idempotency-Key è già stata usata con una richiesta diversa.
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 POST "https://api.eu.keenauth.com/v1/organizations" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Corp","slug":"acme"}'