# 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](/docs/api/fapi/front-api-token)). 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

```bash
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}'
```

```json
{
  "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](/docs/policies/personal-data) 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.