# 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](/docs/api/management/jobs/get-password-reset). Für einen einzelnen Benutzer verwenden Sie [Passwort-Zurücksetzen erzwingen](/docs/api/management/users/force-password-reset).

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.

```json
{
  "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

```bash
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`