Rendi un indirizzo email verificato l'indirizzo principale dell'utente

POST /v1/users/{user_id}/emails/{email_id}:set-primary · autorizzazione users:write

Rende un indirizzo verificato l'indirizzo principale dell'utente; il precedente principale resta come indirizzo secondario. Un indirizzo non verificato non può diventare principale. Se l'indirizzo è già principale non viene scritto nulla e viene restituito 200. La modifica viene scritta nel log di audit di gestione come user.primary_email_changed con la chiave API come attore, e genera user.updated.

Richiesta

Parametro In Obbligatorio Descrizione
user_id path yes ID utente, con prefisso usr_.
email_id path yes ID della riga email (UUID interno, minuscolo, con trattini), come restituito da GET /v1/users/{user_id}/emails.

La richiesta non accetta corpo (sono accettati un corpo vuoto o {}).

Risposta

200 OK con la riga email aggiornata. Senza l'autorizzazione users:read_pii l'indirizzo è mascherato (a***@e***.com).

{
  "id": "0191f0a0-3333-7444-8555-666666666666",
  "email": "ada@example.com",
  "verified": true,
  "primary": true,
  "created_at": "2026-01-15T09:30:00Z"
}

Errori

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

HTTP code Quando
400 malformed_request, unknown_field Il corpo non è JSON valido, oppure non è né vuoto né {}.
409 primary_requires_verified L'indirizzo non è verificato.
404 not_found L'utente o la riga email non esiste in questo ambiente, l'email non appartiene a questo utente, oppure un 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 frequenza; rispetta Retry-After.
503 service_unavailable Una dipendenza non è temporaneamente disponibile; riprova più tardi.

Esempio

curl -X POST https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p/emails/0191f0a0-3333-7444-8555-666666666666:set-primary \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

Dati personali

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