Aggiorna una connessione

PATCH /v1/connections/{connection_id} · autorizzazione connections:write

Aggiorna una connessione con un merge patch JSON (application/merge-patch+json, RFC 7396). If-Match è obbligatorio. key, type, strategy e org_id non possono essere modificati. Una patch che non cambia nulla non scrive nulla e mantiene la versione. Le impostazioni non devono contenere segreti.

Richiesta

Campo Tipo Obbligatorio Descrizione
connection_id string sì Identificatore della connessione (conn_…).
If-Match header sì Il ETag della connessione come letto l'ultima volta. Se manca: 428; se obsoleto: 412.
key string no Non può essere modificato; viene accettato lo stesso valore.
type string no Non può essere modificato.
strategy string no Non può essere modificato.
name string no Da 1 a 128 caratteri.
display_name string | null no null lo cancella.
status string no active o inactive.
org_id string | null no Non può essere modificato; viene accettato lo stesso valore.
allowed_email_domains array di string | null no Sostituisce la lista; null o [] la cancella. Stesse regole della creazione; su una connessione di organizzazione vengono verificati solo i domini appena aggiunti rispetto ai domini verificati dell'organizzazione.
allow_external_domains boolean no Solo enterprise.
jit_mode string no create, create_and_update o off. Solo enterprise.
email_trust boolean no Solo enterprise. Attivarlo per una connessione di organizzazione richiede un allowed_email_domains non vuoto in cui ogni dominio sia un dominio verificato dell'organizzazione.
default_role_ids array di string | null no Sostituisce la lista; null o [] la cancella. Stesse regole della creazione; vengono verificati solo i ruoli appena aggiunti, quindi un ruolo già presente nella lista che è stato eliminato in seguito non blocca l'aggiornamento (viene saltato all'accesso).
trust_idp_mfa boolean no Solo enterprise.
settings object | null no Unito ricorsivamente (RFC 7396); un membro null elimina quella chiave; null cancella tutte le impostazioni. Nessun segreto.

Risposta

200 OK con la connessione aggiornata e il nuovo ETag.

{
  "id": "conn_0k3v8m1q2x9dz4h7s5t6w0y1ab",
  "key": "google",
  "type": "social",
  "strategy": "google",
  "name": "Google",
  "display_name": "Sign in with Google",
  "status": "active",
  "org_id": null,
  "allowed_email_domains": [],
  "allow_external_domains": false,
  "jit_mode": null,
  "email_trust": null,
  "default_role_ids": [],
  "trust_idp_mfa": null,
  "allow_idp_initiated": null,
  "idp_initiated_default_application_id": null,
  "idp_initiated_allowed_application_ids": [],
  "settings": {},
  "created_at": "2026-10-05T09:30:00.123456Z",
  "updated_at": "2026-10-05T09:30:00.123456Z"
}

Impostazioni passkey

Per type: "passkey" l'oggetto settings accetta solo le chiavi sotto elencate. Qualsiasi altra chiave, un tipo errato o un valore fuori intervallo viene rifiutato con 422 validation_failed e un errors[].pointer come /settings/max_credentials_per_user. Il valore null indica il default. Gli errori di forma vengono segnalati prima degli errori di piano.

Chiave Tipo Note
rp_id string Assente, null o vuoto: ogni host di accesso è il proprio rpId. Altrimenti il nome host di un dominio personalizzato active dell'ambiente (minuscolo, etichetta A IDNA); qualsiasi altro valore dà 422 validation_failed (/settings/rp_id). Quando l'ambiente ha passkey, modificalo con Cambia il rpId della passkey.
rp_name string Fino a 128 caratteri.
passkey_first_factor_enabled, security_key_second_factor_enabled boolean Default true.
user_verification string preferred (default) o required.
max_credentials_per_user integer Da 1 a 20, default 20; le frazioni vengono rifiutate.
require_device_bound_passkeys boolean Vincolato al piano: true richiede Startup.
attestation_required boolean Vincolato al piano: true richiede Enterprise.
aaguid_allowlist, aaguid_blocklist array di stringhe UUID Al massimo 500 voci uniche ciascuna (gli errori puntano a /settings/<key>/<index>). Vincolato al piano: una lista non vuota richiede Enterprise.
related_origins array di string Origini https://host[:port]. Vincolato al piano: una lista non vuota richiede Enterprise.
passkey_enrollment_prompt string off o after_login (default).

Scrivere un valore non predefinito di una chiave vincolata al piano fallisce con 403 plan_feature_unavailable e i membri feature e required_plan. Finché le autorizzazioni del piano non sono disponibili, queste chiavi non possono essere impostate in nessun ambiente; scrivere un valore predefinito (false, [], null) o rimuovere la chiave è sempre consentito. Quando la funzione è disponibile, ogni voce di related_origins deve essere un dominio personalizzato verificato e attivo dell'ambiente, altrimenti la richiesta fallisce con 422 related_origin_not_verified. Le impostazioni vengono validate dopo l'applicazione della merge patch, solo quando settings fa parte della patch.

Errori

HTTP code Quando
400 unknown_field La patch contiene un campo sconosciuto o di sola lettura.
404 not_found La connessione non esiste o appartiene a un altro ambiente.
409 connection_test_required La patch imposta una connessione enterprise su active, oppure aggiunge un dominio a allowed_email_domains di una connessione active, senza un test riuscito della configurazione risultante nelle ultime 24 ore (vedi Attiva una connessione); non viene scritto nulla. La rimozione di domini non viene verificata.
409 rp_id_change_requires_migration La patch modifica settings.rp_id di una connessione passkey mentre l'ambiente ha passkey che smetterebbero di funzionare; usa Cambia il rpId della passkey. Non viene scritto nulla.
412 precondition_failed If-Match non corrisponde alla versione corrente.
415 unsupported_media_type Il tipo di contenuto non è application/merge-patch+json.
422 validation_failed Un valore non è valido oppure un campo immutabile è stato modificato (code: immutable).
422 related_origin_not_verified Un'origine correlata non è un dominio personalizzato verificato dell'ambiente.
403 plan_feature_unavailable Il piano non include un'impostazione che hai impostato (membri feature, required_plan), ad esempio attestation_required.
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 non è temporaneamente disponibile (ad esempio, il controllo della passkey per una modifica di rp_id non è potuto essere eseguito, quindi non viene scritto nulla); riprova dopo il periodo indicato in Retry-After.

Esempio

curl -X PATCH https://api.eu.keenauth.com/v1/connections/conn_0k3v8m1q2x9dz4h7s5t6w0y1ab \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "1"' \
  -d '{"display_name":"Sign in with Google"}'