사용자 일괄 삭제 작업 생성

POST /v1/jobs/user-deletions · 권한 users:delete 및 jobs:write

비동기 작업 하나로 최대 10,000명의 사용자를 삭제합니다. 각 사용자는 DELETE /v1/users/{user_id}와 같은 삭제 과정을 거칩니다. 사용자는 pending_deletion 상태가 되고, 영구 삭제는 그 뒤에 실행됩니다. 삭제 기록에는 일괄 작업에서 왔다고 표시됩니다. 삭제는 되돌릴 수 없으므로 이 엔드포인트는 두 단계로 동작합니다.

요청을 "dry_run": true와 함께 보냅니다. 아무것도 기록되지 않으며, 응답에는 요청이 삭제할 사용자 수인 matched_count가 담깁니다.
같은 선택 조건을 "confirm_count"를 그 숫자로 설정해 보냅니다. 그 사이에 일치하는 사용자 수가 바뀌었다면 요청은 409 confirmation_mismatch로 실패하고 작업이 생성되지 않습니다. 이때는 드라이 런을 다시 실행하십시오.

사용자는 두 가지 방법 중 하나로 선택합니다. user_ids(중복된 ID는 한 번만 계산되며, 결과는 처음 나타난 순서를 유지합니다) 또는 organization_id(작업이 생성되는 순간의 조직 활성 및 정지 구성원)입니다. 사용자와 일치하지 않는 ID는 작업에 그대로 남고 not_found로 보고됩니다.

환경에서는 한 번에 하나의 일괄 사용자 삭제 작업만 실행됩니다. 실행 중에 새 작업을 요청하면 Retry-After와 함께 429 rate_limited로 거부됩니다. 작업은 생성될 때와 완료될 때 관리 감사 로그에 기록되며, 삭제된 각 사용자는 자체 삭제 감사 항목도 가집니다. 작업을 추적하려면 일괄 사용자 삭제 작업 조회를 사용하고, 사용자별 결과는 일괄 사용자 삭제 결과 목록에서 읽으십시오.

요청

헤더: Idempotency-Key(필수, 16–64자 A-Z a-z 0-9 _ -). 같은 키와 같은 본문으로 요청을 반복하면 처음 생성된 작업이 반환됩니다. 같은 키에 다른 본문을 보내면 422 idempotency_key_reuse로 실패합니다. 본문은 512 KiB까지 가능합니다.

필드	유형	필수	설명
`user_ids`	문자열 배열	둘 중 하나	`usr_` 접두사가 붙은 사용자 ID, 1개에서 10,000개.
`organization_id`	문자열	둘 중 하나	`org_` 접두사가 붙은 조직 ID. 구성원은 최대 10,000명.
`dry_run`	불리언	아니요	`true`이면 사용자 수만 셉니다. 아무것도 기록되지 않습니다. 기본값 `false`.
`confirm_count`	정수	`dry_run`이 아니면 예	드라이 런의 `matched_count`(0–10,000).

응답

드라이 런: {"dry_run": true, "matched_count": n}과 함께 200 OK.

작업 생성됨: 개수와 작업이 담긴 202 Accepted.

{
  "dry_run": false,
  "matched_count": 2,
  "job": {
    "id": "job_01h455vb4pex5vsknk084sn02q",
    "status": "running",
    "filter": "user_ids",
    "total": 3,
    "succeeded": 0,
    "not_found": 0,
    "failed": 0,
    "pending": 3,
    "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`	키에 `users:delete` 또는 `jobs:write`가 없습니다.
409	`confirmation_mismatch`	`confirm_count`가 현재 일치하는 사용자 수와 다릅니다.
409	`idempotency_in_progress`	같은 `Idempotency-Key`를 가진 요청이 아직 처리 중입니다.
413	`payload_too_large`	본문이 512 KiB보다 큽니다.
422	`validation_failed`	`user_ids`와 `organization_id`가 둘 다 있거나 둘 다 없음, ID 형식 오류, 사용자 10,000명 초과(`too_many`, `too_many_users`), 구성원이 없는 조직(`no_users`), 또는 `confirm_count` 누락(`required`).
422	`idempotency_key_reuse`	`Idempotency-Key`가 다른 본문과 함께 사용되었습니다.
429	`rate_limited`	다른 일괄 사용자 삭제 작업이 실행 중이거나 요청 한도를 초과했습니다. `Retry-After`를 따르십시오.
503	`service_unavailable`	의존 서비스를 일시적으로 사용할 수 없습니다. 나중에 다시 시도하십시오.

예제

curl -X POST https://api.eu.keenauth.com/v1/jobs/user-deletions \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"organization_id": "org_01h455vb4pex5vsknk084sn02q", "dry_run": true}'

CLI: keenauth jobs user-deletions create --organization-id org_01h455vb4pex5vsknk084sn02q --dry-run --yes, 이후 keenauth jobs user-deletions create --organization-id org_01h455vb4pex5vsknk084sn02q --confirm-count 42 --yes. ID 목록이 길면 파일에 담으십시오: --data @users.json.