Creare un job di reimpostazione della password in blocco

POST /v1/jobs/password-resets · permesso user-credentials:write

Obbliga molti utenti a scegliere una nuova password in un unico job asincrono, per esempio dopo una sospetta fuga di dati o per spostare gli utenti da formati di hash importati e deboli. La risposta restituisce subito il job; gli utenti vengono contrassegnati in background. Seguire il job con Ottenere un job di reimpostazione della password in blocco. Per un singolo utente usare Forzare una reimpostazione della password.

Selezionare gli utenti in uno dei due modi (non entrambi):

user_ids: fino a 100.000 ID utente; gli ID ripetuti contano una volta. Gli ID che non sono utenti di questo ambiente, e gli utenti senza password, sono contati come not_found.
hash_algos: ogni utente la cui password è memorizzata con uno di questi algoritmi e che l'ha cambiata per l'ultima volta prima della creazione del job (per esempio ["md5", "phpass"]). Una password impostata dopo la creazione del job non viene selezionata.

Il filtro connection_id non è ancora disponibile; una richiesta che lo invia viene rifiutata con 422 validation_failed (not_supported su /connection_id).

Scegliere il mode:

on_login: ogni utente selezionato deve impostare una nuova password dopo il suo prossimo accesso riuscito con password.
lazy_then_bulk_reset: lo stesso, fino alla scadenza (deadline_days, da 1 a 365, predefinito 30). Alla scadenza, l'hash della password di ogni utente selezionato che non ha ancora cambiato password viene eliminato e viene inviata un'e-mail di reimpostazione all'indirizzo e-mail principale verificato (gli utenti senza uno possono comunque richiedere una reimpostazione da soli). deadline_days è accettato solo in questa modalità.

Idempotency-Key è obbligatoria. Stessa credenziale, stessa chiave e stessa richiesta restituiscono lo stesso job (con Idempotent-Replayed: true); la stessa chiave con una richiesta diversa viene rifiutata con 422 idempotency_key_reuse. Un ambiente può avere al massimo 20 job non completati; un job lazy resta aperto fino alla sua scadenza. La creazione del job viene scritta nel log di audit di gestione (password_reset_job.created) e genera l'evento password_reset.scheduled.

Richiesta

Campo	Tipo	Obbligatorio	Descrizione
`mode`	string	sì	`on_login` oppure `lazy_then_bulk_reset`.
`user_ids`	string[]	uno dei due	Da 1 a 100.000 ID utente (`usr_…`).
`hash_algos`	string[]	uno dei due	Algoritmi di hash memorizzati: `argon2id`, `argon2i`, `bcrypt`, `scrypt`, `firebase_scrypt`, `pbkdf2_sha1`, `pbkdf2_sha256`, `pbkdf2_sha512`, `django_pbkdf2_sha256`, `django_bcrypt_sha256`, `phpass`, `ldap_ssha`, `ldap_ssha256`, `sha512_crypt`, `hmac_sha256`, `salted_sha256`, `salted_sha512`, `md5`.
`deadline_days`	integer	no	Solo `lazy_then_bulk_reset`: da 1 a 365, predefinito 30.

Risposta

202 Accepted con il job.

{
  "id": "job_01h455vb4pex5vsknk084sn02q",
  "mode": "lazy_then_bulk_reset",
  "filter": "hash_algo",
  "hash_algos": ["md5", "phpass"],
  "status": "marking",
  "deadline_at": "2026-02-14T09:30:00Z",
  "total": 0,
  "marked": 0,
  "not_found": 0,
  "passwords_deleted": 0,
  "emailed": 0,
  "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`	L'intestazione `Idempotency-Key` è mancante o non valida, il corpo non è JSON valido oppure ha un campo sconosciuto.
401	`unauthenticated`	La chiave API è mancante, non valida o revocata.
403	`insufficient_permissions`	La chiave non ha il permesso `user-credentials:write`.
409	`conflict`	L'ambiente ha già 20 job non completati.
413	`payload_too_large`	Il corpo supera 4 MiB.
422	`validation_failed`	Un campo manca o non è valido; `errors[].pointer` lo indica.
422	`idempotency_key_reuse`	La `Idempotency-Key` è stata usata con una richiesta diversa.
429	`rate_limited`	È stato superato il limite di frequenza; rispettare `Retry-After`.
503	`service_unavailable`	Una dipendenza non è temporaneamente disponibile; riprovare più tardi.

Esempio

curl -X POST https://api.eu.keenauth.com/v1/jobs/password-resets \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"mode": "lazy_then_bulk_reset", "hash_algos": ["md5", "phpass"], "deadline_days": 30}'

CLI: keenauth jobs password-resets create --mode lazy_then_bulk_reset --hash-algos md5,phpass --deadline-days 30 --yes