# 一括ユーザー削除ジョブを作成

`POST /v1/jobs/user-deletions` · 権限 `users:delete` および `jobs:write`

最大 10,000 人のユーザーを 1 つの非同期ジョブで削除します。各ユーザーには [`DELETE /v1/users/{user_id}`](/docs/api/management/users/delete) と同じ削除処理が適用されます。ユーザーは `pending_deletion` になり、その後で完全な削除が実行されます。削除記録には、一括ジョブから作成されたことが記載されます。削除は取り消せないため、このエンドポイントは次の 2 つの手順で操作します。

1. `"dry_run": true` を指定してリクエストを送信します。何も書き込まれず、レスポンスには `matched_count`（このリクエストで削除されるユーザー数）が含まれます。
2. 同じ選択条件で、`"confirm_count"` にその数を指定してリクエストを送信します。その間に一致するユーザー数が変わっていた場合、リクエストは `409 confirmation_mismatch` で失敗し、ジョブは作成されません。その場合はドライランを再実行してください。

ユーザーの選択方法は 2 通りです。`user_ids`（同じ ID が重複している場合は 1 回として数え、結果は最初に出現した順序を保持します）、または `organization_id`（ジョブ作成時点の組織の有効メンバーおよび停止中のメンバー）。ユーザーに一致しない ID はジョブに保持され、`not_found` として報告されます。

1 つの環境では一括ユーザー削除ジョブを同時に 1 つだけ実行できます。実行中に新しいジョブを作成すると、`429 rate_limited` と `Retry-After` で拒否されます。ジョブは作成時と完了時に管理監査ログへ記録されます。削除された各ユーザーには、個別の削除監査エントリもあります。ジョブの状況は [一括ユーザー削除ジョブを取得](/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` | 文字列の配列 | 2 つのうちいずれか | `usr_` で始まるユーザー ID、1〜10,000 件。 |
| `organization_id` | 文字列 | 2 つのうちいずれか | `org_` で始まる組織 ID。メンバーは最大 10,000 人。 |
| `dry_run` | 真偽値 | いいえ | `true`: ユーザー数を数えるだけで、何も書き込みません。既定値は `false`。 |
| `confirm_count` | 整数 | `dry_run` でない場合は必須 | ドライランの `matched_count`（0〜10,000）。 |

## レスポンス

ドライラン: `200 OK` と `{"dry_run": true, "matched_count": n}`。

ジョブ作成: `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` を指定します。