Inviter un membre

POST /fapi/v1/organizations/{org_id}/invitations · appelé depuis l'hôte de connexion de l'environnement

Invite une adresse e-mail à rejoindre l'organisation. KeenAuth envoie l'e-mail d'invitation ; le jeton d'invitation et le lien d'acceptation ne vous sont jamais renvoyés. Si une invitation en attente existe déjà pour la même adresse avec les mêmes rôles, elle est renvoyée et la réponse est 200 OK ; une nouvelle invitation donne 201 Created.

Le cookie __Host-idp_session de l'utilisateur authentifié est requis, avec un Origin exact, ou le jeton d'accès à l'API front d'une application de première partie (Authorization: DPoP <token> avec une preuve DPoP ; voir Jeton d'accès à l'API front). L'utilisateur doit être un membre actif de l'organisation disposant de l'autorisation idp_members:invite. Un utilisateur qui n'est pas membre reçoit 404 not_found ; un membre sans l'autorisation reçoit 403 insufficient_permissions. Seul un membre disposant du rôle d'administrateur peut inviter avec un rôle privilégié (403 role_not_assignable).

Avec @keenauth/js : const { invitation, resent } = await keenauth.organizations.invite(orgId, { email, roleIds: [roleId] }).

Requête

En-têtes :

En-tête Obligatoire Description
Idp-Client oui Identifiant du SDK.
Origin oui, avec le cookie https://<hôte de connexion>.

org_id : l'identifiant de l'organisation (org_…).

Corps :

Champ Obligatoire Description
email oui L'adresse à inviter, au maximum 254 caractères.
role_ids non Au maximum 10 rôles (rol_…) ; aucun signifie le rôle par défaut de l'organisation.
ttl_days non Durée de validité de l'invitation, de 1 à 30 jours ; la valeur par défaut de l'environnement si omise.

Réponse

201 Created avec Location et ETag, ou 200 OK lorsqu'une invitation en attente a été renvoyée. Le corps est l'invitation :

id (inv_…), email (uniquement tant qu'elle est en attente, sinon null), role_ids, delivery, delivery_status (queued, sent, bounced ou not_sent), status (pending, accepted, revoked ou expired), send_count, last_sent_at, expires_at, accepted_user_id, accepted_at, revoked_at, created_at, updated_at, version.

Erreurs

Statut Code Quand
400 unknown_field Le corps contient un champ non listé ci-dessus.
401 unauthenticated Aucun cookie de session ou jeton valide.
403 insufficient_permissions L'utilisateur ne dispose pas de idp_members:invite dans l'organisation.
403 role_not_assignable Un rôle est privilégié et l'utilisateur ne dispose pas du rôle d'administrateur.
403 origin_not_allowed Origin ne correspond pas.
404 not_found Aucune organisation ou aucun rôle de ce type pour cet utilisateur.
409 invitation_already_pending Une invitation en attente pour cette adresse comporte des rôles différents.
409 membership_already_exists L'adresse appartient à un membre de l'organisation.
409 organization_membership_limit_reached L'organisation a atteint sa limite de membres.
409 organization_disabled L'organisation est désactivée ou en attente de suppression (organization_pending_deletion).
422 validation_failed email, role_ids ou ttl_days est absent ou invalide.
429 invite_rate_limited Trop d'invitations ou de renvois ; réessayez après Retry-After.
501 not_implemented L'envoi d'e-mails d'invitation n'est pas configuré dans cet environnement.
503 service_unavailable Temporairement indisponible ; réessayez après Retry-After.

Exemple

curl -X POST "https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/invitations" \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"email":"new.member@example.com","role_ids":["rol_01jbz6x8kq3m2n4p5r6s7t8v9w"],"ttl_days":7}'

{
  "id": "inv_01jbz6x8kq3m2n4p5r6s7t8v9d",
  "email": "new.member@example.com",
  "role_ids": ["rol_01jbz6x8kq3m2n4p5r6s7t8v9w"],
  "delivery": "email",
  "delivery_status": "queued",
  "status": "pending",
  "send_count": 1,
  "last_sent_at": "2026-11-03T10:00:00Z",
  "expires_at": "2026-11-10T10:00:00Z",
  "accepted_user_id": null,
  "accepted_at": null,
  "revoked_at": null,
  "created_at": "2026-11-03T10:00:00Z",
  "updated_at": "2026-11-03T10:00:00Z",
  "version": 1
}

Données personnelles

Cet point de terminaison contient des données personnelles : appartenances à des organisations et invitations. Données personnelles dans les API KeenAuth décrit ce qui est stocké, la durée de conservation et la manière dont elles sont supprimées. N'envoyez aucune donnée personnelle sensible (santé, données biométriques, religion, opinions politiques, orientation sexuelle) dans un champ quel qu'il soit.