Avvia il recupero dell'account per un utente

POST /v1/users/{user_id}:start-recovery · autorizzazione user-credentials:write

Invia un link di recupero (valido per 24 ore) all'email principale dell'utente senza un periodo di attesa; è il percorso della modalità di recupero admin_only. La richiesta viene aperta direttamente come ready, e una richiesta di recupero aperta viene sostituita nella stessa transazione (superseded). Il link non viene mai restituito. Il corpo opzionale serve solo a selezionare la lingua dell'email. Invia un header Idempotency-Key per rendere sicuri i tentativi ripetuti.

Richiesta

Parametro In Obbligatorio Descrizione
user_id path sì ID utente, con prefisso usr_.

Corpo opzionale:

Campo Tipo Obbligatorio Descrizione
locale string no Tag della lingua BCP 47 dell'email, ad esempio tr o pt-BR. Il valore predefinito è la lingua dell'utente o dell'ambiente.

Risposta

200 OK. request_id identifica la richiesta di recupero (prefisso arq_); superseded indica se una richiesta aperta è stata sostituita.

{
  "request_id": "arq_0a1b2c3d4e5f6g7h8j9k0m1n2p",
  "expires_at": "2026-01-16T09:30:00Z",
  "superseded": false
}

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 contiene un campo sconosciuto.
409 conflict Il recupero dell'account è disabled nelle impostazioni dell'ambiente, oppure l'utente non ha un'email principale.
415 unsupported_media_type È stato inviato un corpo senza Content-Type: application/json.
422 validation_failed locale non è un tag della lingua BCP 47 valido, oppure un campo ha un tipo errato.
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 user-credentials:write.
429 rate_limited È stato superato il limite di richieste; rispetta Retry-After.
503 service_unavailable Una dipendenza è temporaneamente non disponibile; riprova più tardi.

Esempio

curl -X POST https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p:start-recovery \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"locale": "en"}'