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}: 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 y lea los resultados por usuario con Listar los resultados de eliminación masiva de usuarios.

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.

{
  "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

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.