# 사용자 일괄 삭제 작업 생성

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

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

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

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

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

## 요청

**헤더**: `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`.

```json
{
  "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` | 의존 서비스를 일시적으로 사용할 수 없습니다. 나중에 다시 시도하십시오. |

## 예제

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