Aggiorna un utente

PATCH /v1/users/{user_id} · autorizzazione users:write

Aggiorna un utente con una JSON merge patch (Content-Type: application/merge-patch+json). Cambiano solo i campi che invii. I campi di testo si svuotano con null o con una stringa vuota; email_verified e phone_verified non possono essere svuotati; address viene sostituito per intero; user_metadata e app_metadata vengono uniti chiave per chiave e un valore null elimina quella chiave; inviare user_metadata o app_metadata stessi come null elimina tutto e lascia {}. Lo stato non può essere modificato qui: usa blocca e sblocca. Un utente in attesa di eliminazione non può essere aggiornato. If-Match è facoltativo: se viene inviato deve corrispondere all'ETag corrente dell'utente.

Richiesta

Parametro In Obbligatorio Descrizione
user_id path sì ID dell'utente, con prefisso usr_.
If-Match header no L'ETag di una lettura precedente.

Il body accetta gli stessi campi di Crea un utente, tutti facoltativi, più i campi di età indicati sotto. I campi sconosciuti vengono rifiutati con unknown_field.

Età e consenso dei genitori

Quando il tuo processo di verifica dell'età o di consenso dei genitori termina, registra il suo risultato sull'utente con questi campi. Sono restituiti anche in ogni oggetto utente; null significa che l'utente non è stato valutato.

Campo Valori Note
age_group adult, minor, unknown Non può essere svuotato; invia unknown quando l'età non è nota.
parental_consent_status not_required, pending, granted, denied, revoked null lo svuota. Qualsiasi valore diverso da not_required è accettato solo quando age_group dell'utente è minor.
age_assurance_level self_declared, birthdate_declared, third_party_verified null lo svuota. Indica quanto solidamente il tuo processo ha stabilito l'età.

Una modifica a age_group o a parental_consent_status emette un evento user.updated. Non inserire una data di nascita o un numero di documento d'identità in questi campi o nei metadati per supportarli; invia solo il risultato.

Risposta

200 OK. Il body è l'oggetto utente. L'header ETag riporta la versione dell'utente.

I dati personali vengono mascherati quando la chiave non ha l'autorizzazione users:read_pii: email diventa a***@e***.com, phone_number mantiene solo le ultime 2 cifre (+**********67), name, given_name, family_name, middle_name e nickname diventano iniziali (A. L.), username mantiene solo il primo carattere (a***), birthdate diventa ****-**-** e address diventa {"redacted": true}. user_metadata e app_metadata non vengono mascherati.

{
  "id": "usr_0a1b2c3d4e5f6g7h8j9k0m1n2p",
  "kind": "regular",
  "status": "active",
  "external_id": null,
  "username": null,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "email_verified": true,
  "phone_number": null,
  "phone_verified": false,
  "age_group": "adult",
  "parental_consent_status": null,
  "age_assurance_level": "self_declared",
  "user_metadata": {},
  "app_metadata": {},
  "created_via": "admin_api",
  "created_at": "2026-01-15T09:30:00Z",
  "updated_at": "2026-01-15T09:30:00Z",
  "last_sign_in_at": null,
  "deletion_requested_at": null,
  "deletion_due_at": null
}

Errori

Ogni errore è un body application/problem+json con un code stabile.

HTTP code Quando
400 malformed_request, unknown_field La patch non è un oggetto JSON, oppure un campo non è nello schema; oppure If-Match è malformato.
409 conflict Il valore è già in uso, oppure l'utente è in attesa di eliminazione (errors[].code è user_pending_deletion).
412 precondition_failed If-Match non corrisponde alla versione corrente.
415 unsupported_media_type Content-Type non è application/merge-patch+json.
422 validation_failed Un valore non è valido o ha il tipo sbagliato; errors[].pointer indica il campo.
404 not_found L'utente non esiste in questo ambiente (oppure l'ID è malformato).
401 unauthenticated La chiave API manca, non è valida o è stata revocata.
403 insufficient_permissions La chiave non ha l'autorizzazione users:write.
429 rate_limited È stato superato il limite di richieste; rispetta Retry-After.
503 service_unavailable Una dipendenza non è disponibile temporaneamente; riprova più tardi.

Esempio

curl -X PATCH https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"name": "Ada King", "app_metadata": {"tier": "gold"}}'

Registra un consenso dei genitori concesso per un minore:

curl -X PATCH https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"age_group": "minor", "parental_consent_status": "granted", "age_assurance_level": "third_party_verified"}'

Dati personali

Questo endpoint contiene dati personali: profilo dell'utente finale. Dati personali nelle API di KeenAuth descrive cosa viene memorizzato, per quanto tempo viene conservato e come viene eliminato. Non inviare categorie particolari di dati personali (salute, dati biometrici, religione, opinioni politiche, orientamento sessuale) in nessun campo.