Aggiungi un indirizzo email
POST /fapi/v1/me/emails · chiamato dall'host di accesso dell'ambiente
Aggiunge un indirizzo email all'utente autenticato come indirizzo non verificato e non principale, e invia a quell'indirizzo un link di verifica. L'indirizzo diventa utilizzabile quando l'utente apre il link. Ogni richiesta accettata risponde con 202 senza corpo, anche quando l'indirizzo è già uno dei suoi; la risposta non indica mai se l'indirizzo è in uso su un altro account. Un utente può avere al massimo 10 indirizzi, incluso quello principale. Richiede il cookie __Host-idp_session dell'utente autenticato; se il cookie manca, è scaduto o è stato revocato, restituisce 401 unauthenticated. Un'app di prima parte su un'altra origine può invece inviare il proprio token di accesso Front API (Authorization: DPoP <token> con una prova DPoP; vedi Token di accesso Front API).
La sessione deve essere stata verificata negli ultimi 5 minuti. Se l'utente ha un secondo fattore, la sessione deve inoltre essere stata aperta con un secondo fattore (urn:idp:acr:mfa).
Richiesta
Intestazioni:
| Intestazione | Obbligatoria | Descrizione |
|---|---|---|
Idp-Client |
sì | Identificatore dell'SDK. |
Origin |
sì | Deve essere esattamente https://<sign-in host>. |
Content-Type |
sì | application/json. |
Corpo:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
email |
string | sì | L'indirizzo da aggiungere (al massimo 320 caratteri). |
Risposta
202 Accepted, senza corpo.
Errori
| Stato | Codice | Quando |
|---|---|---|
| 400 | malformed_request |
Il corpo non è JSON valido. |
| 400 | unknown_field |
Il corpo contiene un campo diverso da email. |
| 401 | unauthenticated |
Cookie di sessione assente o non valido. |
| 401 | step_up_required |
La sessione non è stata verificata negli ultimi 5 minuti oppure è richiesto un secondo fattore; verifica di nuovo con max_age=300 (e, se applicabile, acr_values) nell'intestazione WWW-Authenticate. |
| 403 | origin_not_allowed |
Origin manca o è errato. |
| 409 | email_limit_reached |
L'utente ha già 10 indirizzi email. |
| 413 | payload_too_large |
Il corpo è troppo grande. |
| 415 | unsupported_media_type |
Content-Type non è application/json. |
| 422 | validation_failed |
email manca. |
| 422 | email_invalid |
email non è un indirizzo email valido. |
| 422 | email_domain_not_allowed |
L'ambiente non consente indirizzi con questo dominio. |
| 429 | verification_rate_limited |
Sono stati inviati troppi messaggi di verifica di recente; riprova più tardi. |
Esempio
curl -X POST https://example.keenauth.app/fapi/v1/me/emails \
-H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
-H "Origin: https://example.keenauth.app" \
-H "Content-Type: application/json" \
-b cookies.txt \
-d '{"email": "ada@example.org"}'
Dati personali
Questo endpoint contiene dati personali: profilo dell'utente finale. Dati personali nelle API KeenAuth descrive cosa viene archiviato, 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.