# Crear un trabajo de eliminación masiva de usuarios

`POST /v1/jobs/user-deletions` · permisos `users:delete` y `jobs:write`

Elimina hasta 10.000 usuarios en un único trabajo asíncrono. Cada usuario pasa por la misma eliminación que [`DELETE /v1/users/{user_id}`](/docs/api/management/users/delete): el usuario pasa a `pending_deletion` y la eliminación permanente se ejecuta después; el registro de eliminación indica que procede de un trabajo masivo. La eliminación no se puede deshacer, así que el endpoint funciona en dos pasos:

1. Envíe la solicitud con `"dry_run": true`. No se escribe nada; la respuesta contiene `matched_count`, el número de usuarios que la solicitud eliminaría.
2. Envíe la misma selección con `"confirm_count"` establecido en ese número. Si el número de usuarios coincidentes ha cambiado entre tanto, la solicitud falla con `409 confirmation_mismatch` y no se crea ningún trabajo; vuelva a ejecutar la simulación.

Seleccione los usuarios de una de dos maneras: `user_ids` (los ids repetidos cuentan una vez; los resultados mantienen el orden de primera aparición) u `organization_id` (los miembros activos y suspendidos de la organización en el momento en que se crea el trabajo). Los ids que no coinciden con ningún usuario se conservan en el trabajo y se informan como `not_found`.

Solo se ejecuta un trabajo de eliminación masiva de usuarios a la vez en un entorno; mientras uno está en curso, un nuevo trabajo se rechaza con `429 rate_limited` y `Retry-After`. El trabajo se escribe en el registro de auditoría de gestión al crearse y al completarse; cada usuario eliminado tiene además su propia entrada de auditoría de eliminación. Haga seguimiento del trabajo con [Obtener un trabajo de eliminación masiva de usuarios](/docs/api/management/jobs/get-user-deletion) y lea los resultados por usuario con [Listar los resultados de eliminación masiva de usuarios](/docs/api/management/jobs/list-user-deletion-results).

## Solicitud

**Encabezados**: `Idempotency-Key` (obligatorio, de 16 a 64 caracteres `A-Z a-z 0-9 _ -`). Repetir la solicitud con la misma clave y el mismo cuerpo devuelve el primer trabajo; la misma clave con un cuerpo distinto falla con `422 idempotency_key_reuse`. El cuerpo puede tener hasta 512 KiB.

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `user_ids` | array de cadenas | uno de los dos | Ids de usuario con prefijo `usr_`, de 1 a 10.000. |
| `organization_id` | cadena | uno de los dos | Id de organización con prefijo `org_`; como máximo 10.000 miembros. |
| `dry_run` | booleano | no | `true`: solo cuenta los usuarios; no se escribe nada. Predeterminado `false`. |
| `confirm_count` | entero | sí, salvo `dry_run` | El `matched_count` de la simulación (0–10.000). |

## Respuesta

Simulación: `200 OK` con `{"dry_run": true, "matched_count": n}`.

Trabajo creado: `202 Accepted` con el recuento y el trabajo.

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

## Errores

Cada error es un cuerpo `application/problem+json` con un `code` estable.

| HTTP | `code` | Cuándo |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | Falta el encabezado `Idempotency-Key` o no es válido, o el cuerpo no es JSON válido o tiene un campo desconocido. |
| 401 | `unauthenticated` | La clave de API falta, no es válida o está revocada. |
| 403 | `insufficient_permissions` | La clave no tiene `users:delete` o `jobs:write`. |
| 409 | `confirmation_mismatch` | `confirm_count` no es el número actual de usuarios coincidentes. |
| 409 | `idempotency_in_progress` | Una solicitud con la misma `Idempotency-Key` todavía se está procesando. |
| 413 | `payload_too_large` | El cuerpo supera los 512 KiB. |
| 422 | `validation_failed` | Ambos o ninguno de `user_ids` y `organization_id`, un id con formato incorrecto, más de 10.000 usuarios (`too_many`, `too_many_users`), una organización sin miembros (`no_users`) o un `confirm_count` ausente (`required`). |
| 422 | `idempotency_key_reuse` | La `Idempotency-Key` se usó con un cuerpo distinto. |
| 429 | `rate_limited` | Hay otro trabajo de eliminación masiva de usuarios en curso, o se superó el límite de frecuencia; respete `Retry-After`. |
| 503 | `service_unavailable` | Una dependencia no está disponible temporalmente; reintente más tarde. |

## Ejemplo

```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`, luego `keenauth jobs user-deletions create --organization-id org_01h455vb4pex5vsknk084sn02q --confirm-count 42 --yes`. Las listas largas de ids van en un archivo: `--data @users.json`.