Aggiorna le impostazioni dell'ambiente

PATCH /v1/environment-settings · autorizzazione environment-settings:write

Aggiorna le impostazioni dell'ambiente con un JSON merge patch (application/merge-patch+json, RFC 7396). If-Match è obbligatorio: se manca restituisce 428, se la versione è obsoleta restituisce 412. Se le impostazioni non sono mai state scritte, la versione è "0" e la prima scrittura crea la riga. Una patch che non cambia nulla non scrive nulla e mantiene la versione.

Richiesta

Campo Tipo Obbligatorio Descrizione
If-Match header sì Il ETag delle impostazioni così come letto l'ultima volta ("0" se non sono mai state scritte). Se manca: 428; se obsoleto: 412.
locales.enabled string[] no Codici lingua abilitati (lingue registrate), da 1 a 64 voci, senza duplicati. Non può essere null.
locales.default string no Lingua predefinita; deve essere una di locales.enabled. Non può essere null.
default_zoneinfo string no Nome del fuso orario IANA (predefinito UTC). Non può essere null.
session.idle_timeout_s integer no Timeout di inattività in secondi, da 60 a 8640000 (predefinito 259200); non maggiore di session.absolute_timeout_s. Non può essere null.
session.absolute_timeout_s integer no Durata assoluta in secondi, da 60 a 31536000 (predefinito 2592000). Non può essere null.
session.max_concurrent integer no Sessioni simultanee per utente, da 0 a 500; 0 significa il limite di sistema (predefinito). Non può essere null.
session.concurrent_mode string no evict_oldest (predefinito) o deny_new. Non può essere null.
session.anomaly_action string no enforce (predefinito) o log. Non può essere null.
signup.mode string no open (predefinito), invite_only o closed. Non può essere null.
signup.email_domain_mode string no off (predefinito), allowlist o denylist. Non può essere null.
signup.email_domains string[] | null no Al massimo 1000 domini; sostituisce l'intera lista (RFC 7396 non unisce gli array). null o [] la svuotano. Le voci sono normalizzate (minuscole, A-label IDNA), i duplicati vengono eliminati e la lista è memorizzata ordinata. Viene mantenuta mentre la modalità è off.
security_notifications.enabled boolean no Interruttore generale (predefinito true). Non può essere null.
security_notifications.events string[] | null no Sottoinsieme dei 12 eventi di sicurezza (password_changed, password_reset, email_changed, phone_changed, authenticator_added, authenticator_removed, recovery_code_used, recovery_codes_regenerated, account_locked, breached_password_detected, new_device_sign_in, account_recovery_started); sostituisce l'intera lista e viene restituita nell'ordine canonico. null o [] la svuotano (nessun evento).
account_recovery.mode string no self_service_waiting (predefinito), admin_only o disabled. Non può essere null.
account_recovery.waiting_hours integer no Da 24 a 168 ore (predefinito 72); memorizzato in ogni modalità. Non può essere null.
account_recovery.support_url string no Vuoto oppure un URL https:// di al massimo 2048 byte, senza informazioni utente o frammento. Mostrato quando il recupero è disabled. Non può essere null.
mfa.email_second_factor_enabled boolean no Secondo fattore via email attivo o disattivo (predefinito false). Non può essere null.
mfa.email_second_factor_acr string no Livello di garanzia attribuito al fattore email: 1fa (predefinito) o mfa. Non può essere null.
mfa.totp_issuer_label string no Etichetta dell'emittente TOTP, al massimo 64 caratteri; vuota significa il nome visualizzato dell'ambiente. Nessun carattere di controllo, : o spazi iniziali/finali. Non può essere null.
mfa.recovery_codes_enabled boolean no Codici di recupero attivi o disattivi (predefinito true). Non può essere null.
mfa.recovery_code_count integer no Numero di codici di recupero, da 8 a 16 (predefinito 10). Non può essere null.
mfa.required boolean no Richiede un secondo fattore a ogni accesso nell'ambiente (predefinito false). Combinato con OR con i requisiti dell'applicazione, dell'organizzazione e della richiesta; una sessione SSO esistente al di sotto di questo livello viene portata a un livello superiore (interaction_required con prompt=none). Non può essere null.
mfa.min_acr string no Livello di garanzia minimo che ogni accesso nell'ambiente deve raggiungere: 1fa (predefinito, nessun effetto), mfa o phr. Si applica la soglia più alta tra quelle di ambiente, applicazione, organizzazione e richiesta, per i nuovi accessi e per il riuso della sessione SSO. Non può essere null.
mfa.enrollment_grace_days integer no Giorni in cui un utente senza secondo fattore può continuare ad accedere senza registrarsi, contati dalla prima volta in cui gli viene richiesta la registrazione, da 0 a 14 (predefinito 0, nessuna tolleranza). La tolleranza posticipa solo ciò che richiedono gli assi di ambiente e organizzazione; il min_acr di un'applicazione e i acr_values richiesti non vengono mai posticipati. Un valore fuori intervallo restituisce 422 validation_failed con out_of_range. Ridurlo ha effetto immediato. Non può essere null.
frontchannel_logout_enabled boolean no Front-Channel Logout attivo o disattivo (predefinito false); disattivarlo mantiene gli URI registrati. Non può essere null.
allowed_first_factors string[] no Primi fattori consentiti: almeno uno tra password, passkey, email_otp, magic_link, sms_otp, social, enterprise, senza duplicati. Sostituisce l'intera lista e viene restituita in questo ordine. Predefiniti password, passkey, social, enterprise; email_otp, magic_link e sms_otp sono attivi solo se aggiunti esplicitamente. Una lista vuota restituisce 422 required (un ambiente in cui nessuno potrebbe accedere). Non può essere null.

Comportamento

Risposta

200 OK con le impostazioni aggiornate e il nuovo ETag.

{
  "locales": {"enabled": ["en", "tr"], "default": "tr"},
  "default_zoneinfo": "Europe/Istanbul",
  "session": {"idle_timeout_s": 3600, "absolute_timeout_s": 2592000, "max_concurrent": 5, "concurrent_mode": "evict_oldest", "anomaly_action": "enforce"},
  "signup": {"mode": "invite_only", "email_domain_mode": "allowlist", "email_domains": ["example.com"]},
  "security_notifications": {"enabled": true, "events": ["password_changed", "password_reset"]},
  "account_recovery": {"mode": "self_service_waiting", "waiting_hours": 72, "support_url": ""},
  "mfa": {"email_second_factor_enabled": false, "email_second_factor_acr": "1fa", "totp_issuer_label": "Acme", "recovery_codes_enabled": true, "recovery_code_count": 10, "required": false, "min_acr": "1fa", "enrollment_grace_days": 0},
  "frontchannel_logout_enabled": false,
  "allowed_first_factors": ["password", "passkey", "magic_link", "enterprise"],
  "updated_at": "2026-10-05T09:30:00.123456Z"
}

Errori

HTTP code Quando
400 unknown_field La patch contiene un campo sconosciuto o di sola lettura, oppure non è un oggetto JSON (malformed_request).
412 precondition_failed If-Match non corrisponde alla versione corrente.
415 unsupported_media_type Il content type non è application/merge-patch+json.
422 validation_failed Un valore non è valido (il puntatore indica il campo), oppure un campo che non può essere null è stato impostato a null (code: invalid).
422 policy_conflict Il nuovo allowed_first_factors non lascia alcun metodo in comune con un'applicazione che ha un insieme proprio.
428 precondition_required L'header If-Match manca.
401 unauthenticated La credenziale manca, non è valida o è stata revocata.
403 insufficient_permissions La credenziale non ha l'autorizzazione richiesta.
429 rate_limited È stato superato il limite di richieste; riprova dopo il periodo indicato in Retry-After.
503 service_unavailable Una dipendenza è temporaneamente non disponibile; riprova dopo il periodo indicato in Retry-After.

Esempio

Attiva i magic link via email e disattiva le password:

curl -X PATCH https://api.eu.keenauth.com/v1/environment-settings \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "0"' \
  -d '{"allowed_first_factors":["passkey","magic_link","social","enterprise"]}'

Impostazioni di sessione e registrazione:

curl -X PATCH https://api.eu.keenauth.com/v1/environment-settings \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "0"' \
  -d '{"session":{"idle_timeout_s":3600},"signup":{"mode":"invite_only","email_domain_mode":"allowlist","email_domains":["example.com"]}}'