# Créer une tâche de suppression d'utilisateurs en masse

`POST /v1/jobs/user-deletions` · autorisations `users:delete` et `jobs:write`

Supprime jusqu'à 10 000 utilisateurs dans une seule tâche asynchrone. Chaque utilisateur passe par la même suppression que [`DELETE /v1/users/{user_id}`](/docs/api/management/users/delete) : l'utilisateur passe à `pending_deletion` et la suppression définitive s'exécute ensuite ; l'enregistrement de suppression indique qu'elle provient d'une tâche en masse. La suppression ne peut pas être annulée, donc le point de terminaison fonctionne en deux étapes :

1. Envoyez la requête avec `"dry_run": true`. Rien n'est écrit ; la réponse contient `matched_count`, le nombre d'utilisateurs que la requête supprimerait.
2. Envoyez la même sélection avec `"confirm_count"` défini à ce nombre. Si le nombre d'utilisateurs correspondants a changé entre-temps, la requête échoue avec `409 confirmation_mismatch` et aucune tâche n'est créée ; relancez alors la simulation.

Sélectionnez les utilisateurs de l'une des deux façons : `user_ids` (les identifiants répétés ne comptent qu'une fois ; les résultats gardent l'ordre de première apparition) ou `organization_id` (les membres actifs et suspendus de l'organisation au moment de la création de la tâche). Les identifiants qui ne correspondent à aucun utilisateur sont conservés dans la tâche et signalés comme `not_found`.

Une seule tâche de suppression d'utilisateurs en masse s'exécute à la fois dans un environnement ; pendant qu'une tâche est en cours, une nouvelle tâche est refusée avec `429 rate_limited` et `Retry-After`. La tâche est écrite dans le journal d'audit de gestion à sa création et à son achèvement ; chaque utilisateur supprimé possède aussi sa propre entrée d'audit de suppression. Suivez la tâche avec [Obtenir une tâche de suppression d'utilisateurs en masse](/docs/api/management/jobs/get-user-deletion) et lisez les résultats par utilisateur avec [Lister les résultats de suppression d'utilisateurs en masse](/docs/api/management/jobs/list-user-deletion-results).

## Demande

**En-têtes** : `Idempotency-Key` (obligatoire, 16 à 64 caractères `A-Z a-z 0-9 _ -`). Répéter la requête avec la même clé et le même corps renvoie la première tâche ; la même clé avec un corps différent échoue avec `422 idempotency_key_reuse`. Le corps peut atteindre 512 Kio.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `user_ids` | tableau de chaînes | l'un des deux | Identifiants d'utilisateurs préfixés `usr_`, de 1 à 10 000. |
| `organization_id` | chaîne | l'un des deux | Identifiant d'organisation préfixé `org_` ; 10 000 membres au maximum. |
| `dry_run` | booléen | non | `true` : compte seulement les utilisateurs ; rien n'est écrit. Par défaut `false`. |
| `confirm_count` | entier | oui, sauf si `dry_run` | Le `matched_count` de la simulation (0–10 000). |

## Réponse

Simulation : `200 OK` avec `{"dry_run": true, "matched_count": n}`.

Tâche créée : `202 Accepted` avec le nombre et la tâche.

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

## Erreurs

Chaque erreur est un corps `application/problem+json` avec un `code` stable.

| HTTP | `code` | Quand |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | L'en-tête `Idempotency-Key` est absent ou invalide, ou le corps n'est pas du JSON valide ou contient un champ inconnu. |
| 401 | `unauthenticated` | La clé d'API est absente, invalide ou révoquée. |
| 403 | `insufficient_permissions` | La clé ne dispose pas de `users:delete` ou `jobs:write`. |
| 409 | `confirmation_mismatch` | `confirm_count` n'est pas le nombre actuel d'utilisateurs correspondants. |
| 409 | `idempotency_in_progress` | Une requête avec la même `Idempotency-Key` est encore en cours de traitement. |
| 413 | `payload_too_large` | Le corps dépasse 512 Kio. |
| 422 | `validation_failed` | Les deux ou aucun des champs `user_ids` et `organization_id`, un identifiant mal formé, plus de 10 000 utilisateurs (`too_many`, `too_many_users`), une organisation sans membres (`no_users`) ou un `confirm_count` absent (`required`). |
| 422 | `idempotency_key_reuse` | La `Idempotency-Key` a été utilisée avec un corps différent. |
| 429 | `rate_limited` | Une autre tâche de suppression d'utilisateurs en masse est en cours, ou la limite de débit a été dépassée ; respectez `Retry-After`. |
| 503 | `service_unavailable` | Une dépendance est temporairement indisponible ; réessayez plus tard. |

## Exemple

```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`, puis `keenauth jobs user-deletions create --organization-id org_01h455vb4pex5vsknk084sn02q --confirm-count 42 --yes`. Les longues listes d'identifiants vont dans un fichier : `--data @users.json`.