Massen-Passwort-Zurücksetzen als Job anlegen

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

Zwingt viele Benutzer in einem asynchronen Job, ein neues Passwort zu wählen, zum Beispiel nach einem vermuteten Datenleck oder um Benutzer von schwachen importierten Hash-Formaten wegzuführen. Die Antwort liefert den Job sofort; die Benutzer werden im Hintergrund markiert. Verfolgen Sie den Job mit Massen-Passwort-Zurücksetzen-Job abrufen. Für einen einzelnen Benutzer verwenden Sie Passwort-Zurücksetzen erzwingen.

Wählen Sie die Benutzer auf eine von zwei Arten aus (nicht beide):

user_ids: bis zu 100.000 Benutzer-IDs; doppelte IDs zählen einmal. IDs, die keine Benutzer dieser Umgebung sind, und Benutzer ohne Passwort werden als not_found gezählt.
hash_algos: jeder Benutzer, dessen Passwort mit einem dieser Algorithmen gespeichert ist und dessen Passwort zuletzt vor dem Anlegen des Jobs geändert wurde (zum Beispiel ["md5", "phpass"]). Ein Passwort, das nach dem Anlegen des Jobs gesetzt wurde, wird nicht ausgewählt.

Der Filter connection_id ist noch nicht verfügbar; eine Anfrage, die ihn sendet, wird mit 422 validation_failed abgelehnt (not_supported unter /connection_id).

Wählen Sie den mode:

on_login: Jeder ausgewählte Benutzer muss nach seiner nächsten erfolgreichen Anmeldung mit Passwort ein neues Passwort festlegen.
lazy_then_bulk_reset: dasselbe bis zur Frist (deadline_days, 1–365, Standard 30). Bei Ablauf der Frist wird der Passwort-Hash jedes ausgewählten Benutzers, der sein Passwort noch nicht geändert hat, gelöscht, und an seine verifizierte primäre E-Mail-Adresse wird eine E-Mail zum Zurücksetzen des Passworts gesendet (Benutzer ohne eine solche können selbst ein Zurücksetzen anfordern). deadline_days wird nur in diesem Modus akzeptiert.

Idempotency-Key ist erforderlich. Dieselben Zugangsdaten, derselbe Schlüssel und dieselbe Anfrage liefern denselben Job (mit Idempotent-Replayed: true); derselbe Schlüssel mit einer anderen Anfrage wird mit 422 idempotency_key_reuse abgelehnt. Eine Umgebung kann höchstens 20 Jobs haben, die nicht abgeschlossen sind; ein Lazy-Job bleibt bis zu seiner Frist offen. Das Anlegen des Jobs wird im Verwaltungs-Audit-Log (password_reset_job.created) festgehalten und löst das Ereignis password_reset.scheduled aus.

Anfrage

Feld	Typ	Pflicht	Beschreibung
`mode`	string	ja	`on_login` oder `lazy_then_bulk_reset`.
`user_ids`	string[]	eines von beiden	1–100.000 Benutzer-IDs (`usr_…`).
`hash_algos`	string[]	eines von beiden	Gespeicherte Hash-Algorithmen: `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	nein	Nur `lazy_then_bulk_reset`: 1–365, Standard 30.

Antwort

202 Accepted mit dem 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"
}

Fehler

Jeder Fehler ist ein application/problem+json-Body mit einem stabilen code.

HTTP	`code`	Wann
400	`malformed_request`, `unknown_field`	Der Header `Idempotency-Key` fehlt oder ist fehlerhaft, der Body ist kein gültiges JSON oder enthält ein unbekanntes Feld.
401	`unauthenticated`	Der API-Schlüssel fehlt, ist ungültig oder widerrufen.
403	`insufficient_permissions`	Dem Schlüssel fehlt die Berechtigung `user-credentials:write`.
409	`conflict`	Die Umgebung hat bereits 20 Jobs, die nicht abgeschlossen sind.
413	`payload_too_large`	Der Body ist größer als 4 MiB.
422	`validation_failed`	Ein Feld fehlt oder ist ungültig; `errors[].pointer` nennt es.
422	`idempotency_key_reuse`	Der `Idempotency-Key` wurde mit einer anderen Anfrage verwendet.
429	`rate_limited`	Das Ratenlimit wurde überschritten; beachten Sie `Retry-After`.
503	`service_unavailable`	Eine Abhängigkeit ist vorübergehend nicht verfügbar; versuchen Sie es später erneut.

Beispiel

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