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} : 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 et lisez les résultats par utilisateur avec Lister les résultats de suppression d'utilisateurs en masse.

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.

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

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.