Créer des invitations en masse

POST /v1/invitations:batch · autorisation invitations:write

Crée de 1 à 100 invitations (items). Chaque élément suit les règles de POST /v1/invitations et est écrit de manière indépendante : un élément en échec n'interrompt pas les autres. La réponse est 200 OK et items conserve l'ordre de la requête ; le status d'un élément est 201 (nouvelle invitation), 200 (une invitation en attente a été renvoyée) ou le statut HTTP de son erreur, et un élément en échec porte un error avec code, status et des pointeurs de champs de la forme /items/<i>/…. Le accept_url des éléments link_only n'est renvoyé que dans cette réponse (Cache-Control: no-store) ; une réponse rejouée avec Idempotency-Key ne contient pas de liens et renvoie secret_redacted: true. Un élément sans organization_id est une invitation à l'environnement. Un élément email est envoyé par e-mail ; si l'envoi d'e-mails d'invitation n'est pas configuré pour ce déploiement, il s'agit d'une erreur d'élément 501 not_implemented, et un application_id qui n'existe pas dans cet environnement est une erreur d'élément 404 not_found. Chaque invitation écrite est journalisée sous invitation.created.

Requête

Champ Type Obligatoire Description
items object[] oui 1 à 100 invitations, chacune avec les champs de POST /v1/invitations.
Idempotency-Key header non Permet à une nouvelle tentative de renvoyer le résultat enregistré, sans liens.

Réponse

200 OK avec un résultat par élément.

{
  "items": [
    {
      "status": 201,
      "invitation": {
        "id": "inv_01j9xt9v3w4y8z0a2b4c6d8e0g",
        "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
        "email": "ada@example.com",
        "role_ids": [
          "rol_01j9xr7s1t2w6x8y0z2a4b6c8e"
        ],
        "application_id": null,
        "delivery": "link_only",
        "delivery_status": "not_sent",
        "status": "pending",
        "send_count": 1,
        "last_sent_at": "2026-10-12T09:31:00.123456Z",
        "expires_at": "2026-10-19T09:31:00.123456Z",
        "accepted_user_id": null,
        "accepted_at": null,
        "revoked_at": null,
        "created_at": "2026-10-12T09:31:00.123456Z",
        "updated_at": "2026-10-12T09:31:00.123456Z",
        "version": 1,
        "accept_url": "https://acme.eu.keenauth.app/u/login?invitation=<token>"
      }
    },
    {
      "status": 422,
      "error": {
        "code": "validation_failed",
        "status": 422,
        "errors": [
          {
            "pointer": "/items/1/email",
            "code": "invalid_value"
          }
        ]
      }
    }
  ]
}

Erreurs

HTTP code Quand
422 validation_failed items est absent, vide ou comporte plus de 100 éléments.
401 unauthenticated L'identifiant d'authentification est absent, invalide ou révoqué.
403 insufficient_permissions L'identifiant ne possède pas l'autorisation requise. Un élément avec un rôle privilégié (is_privileged) échoue avec cette erreur d'élément lorsque l'identifiant ne possède pas roles:write.
429 rate_limited La limite de débit a été dépassée ; réessayez après la période indiquée par Retry-After.
503 service_unavailable Une dépendance est temporairement indisponible ; réessayez après la période indiquée par Retry-After.

Exemple

curl -i -X POST "https://api.eu.keenauth.com/v1/invitations:batch" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0f6c1d2e3a4b5c6d7e8f9a0b" \
  -d '{"items":[{"organization_id":"org_01j9xk3m7q8r2s4t6v8w0y2z4a","email":"ada@example.com","delivery":"link_only"},{"organization_id":"org_01j9xk3m7q8r2s4t6v8w0y2z4a","email":"bob@example.com","delivery":"link_only"}]}'

Données personnelles

Ce point de terminaison traite des données personnelles : les adhésions à une organisation et les invitations. Données personnelles dans les API KeenAuth décrit ce qui est stocké, pendant combien de temps les données sont conservées et comment elles sont supprimées. N'envoyez de catégories particulières de données personnelles (santé, données biométriques, religion, opinions politiques, orientation sexuelle) dans aucun champ.