# 일괄 비밀번호 재설정 작업 생성

`POST /v1/jobs/password-resets` · 권한 `user-credentials:write`

비동기 작업 하나로 많은 사용자가 새 비밀번호를 선택하도록 강제합니다. 예를 들어 유출이 의심될 때나, 사용자를 취약한 가져온 해시 형식에서 옮겨야 할 때 사용합니다. 응답은 작업을 즉시 반환하며, 사용자 표시는 백그라운드에서 이루어집니다. 작업은 [일괄 비밀번호 재설정 작업 조회](/docs/api/management/jobs/get-password-reset)로 추적하십시오. 한 명의 사용자에게는 [비밀번호 재설정 강제 적용](/docs/api/management/users/force-password-reset)을 사용하십시오.

두 가지 방법 중 하나로 사용자를 선택합니다(둘 다 사용할 수는 없습니다).

- `user_ids`: 최대 100,000개의 사용자 ID입니다. 중복된 ID는 한 번만 계산됩니다. 이 환경의 사용자가 아니거나 비밀번호가 없는 ID는 `not_found`로 계산됩니다.
- `hash_algos`: 이 알고리즘 중 하나로 비밀번호가 저장되어 있고, 작업이 생성되기 전에 마지막으로 변경된 모든 사용자입니다(예: `["md5", "phpass"]`). 작업이 생성된 뒤에 설정된 비밀번호는 선택되지 않습니다.

`connection_id` 필터는 아직 지원되지 않습니다. 이를 보내는 요청은 `422 validation_failed`(`/connection_id`에서 `not_supported`)로 거부됩니다.

`mode`를 선택하십시오.

- `on_login`: 선택된 각 사용자는 다음 번 비밀번호 로그인에 성공한 뒤 새 비밀번호를 설정해야 합니다.
- `lazy_then_bulk_reset`: 기한(`deadline_days`, 1–365, 기본값 30)까지 동일합니다. 기한이 되면 아직 비밀번호를 바꾸지 않은 선택된 모든 사용자의 저장된 비밀번호 해시가 삭제되고, 확인된 기본 이메일 주소로 비밀번호 재설정 이메일이 발송됩니다(확인된 주소가 없는 사용자는 직접 재설정을 요청할 수 있습니다). `deadline_days`는 이 모드에서만 허용됩니다.

`Idempotency-Key`는 필수입니다. 같은 자격 증명, 같은 키, 같은 요청은 같은 작업을 반환합니다(`Idempotent-Replayed: true`와 함께). 같은 키에 다른 요청을 보내면 `422 idempotency_key_reuse`로 거부됩니다. 환경은 완료되지 않은 작업을 최대 20개까지 가질 수 있으며, lazy 작업은 기한까지 열려 있습니다. 작업 생성은 관리 감사 로그(`password_reset_job.created`)에 기록되고 `password_reset.scheduled` 이벤트를 발생시킵니다.

## 요청

| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
| `mode` | string | 예 | `on_login` 또는 `lazy_then_bulk_reset`. |
| `user_ids` | string[] | 둘 중 하나 | 1–100,000개의 사용자 ID(`usr_…`). |
| `hash_algos` | string[] | 둘 중 하나 | 저장된 해시 알고리즘: `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 | 아니요 | `lazy_then_bulk_reset` 전용: 1–365, 기본값 30. |

## 응답

`202 Accepted`와 함께 작업을 반환합니다.

```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"
}
```

## 오류

모든 오류는 안정적인 `code`를 담은 `application/problem+json` 본문입니다.

| HTTP | `code` | 발생 시점 |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | `Idempotency-Key` 헤더가 없거나 잘못되었거나, 본문이 유효한 JSON이 아니거나, 알 수 없는 필드가 있습니다. |
| 401 | `unauthenticated` | API 키가 없거나, 잘못되었거나, 취소되었습니다. |
| 403 | `insufficient_permissions` | 키에 `user-credentials:write` 권한이 없습니다. |
| 409 | `conflict` | 환경에 이미 완료되지 않은 작업이 20개 있습니다. |
| 413 | `payload_too_large` | 본문이 4 MiB보다 큽니다. |
| 422 | `validation_failed` | 필드가 없거나 잘못되었습니다. `errors[].pointer`가 해당 필드를 가리킵니다. |
| 422 | `idempotency_key_reuse` | `Idempotency-Key`가 다른 요청에 사용되었습니다. |
| 429 | `rate_limited` | 요청 한도를 초과했습니다. `Retry-After` 값을 따르십시오. |
| 503 | `service_unavailable` | 종속 서비스를 일시적으로 사용할 수 없습니다. 나중에 다시 시도하십시오. |

## 예제

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