일괄 비밀번호 재설정 작업 생성
POST /v1/jobs/password-resets · 권한 user-credentials:write
비동기 작업 하나로 많은 사용자가 새 비밀번호를 선택하도록 강제합니다. 예를 들어 유출이 의심될 때나, 사용자를 취약한 가져온 해시 형식에서 옮겨야 할 때 사용합니다. 응답은 작업을 즉시 반환하며, 사용자 표시는 백그라운드에서 이루어집니다. 작업은 일괄 비밀번호 재설정 작업 조회로 추적하십시오. 한 명의 사용자에게는 비밀번호 재설정 강제 적용을 사용하십시오.
두 가지 방법 중 하나로 사용자를 선택합니다(둘 다 사용할 수는 없습니다).
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와 함께 작업을 반환합니다.
{
"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 |
종속 서비스를 일시적으로 사용할 수 없습니다. 나중에 다시 시도하십시오. |
예제
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