# Cycle de vie d'une invitation

> Les statuts d'une invitation (en attente, acceptée, expirée, annulée), les contrôles à l'envoi et ce que l'acceptation crée.

Une [invitation](/v1.0/glossaire#invitation) propose à une personne de rejoindre un client, avec un profil fixé d'avance, dans l'environnement de celui qui invite. Elle porte un jeton secret, envoyé par e-mail, que la personne présente pour créer son compte.

## Définition

Une invitation contient :

- l'adresse e-mail de la personne invitée, et facultativement son prénom et son nom ;
- le client qu'elle rejoint et le [profil](/v1.0/glossaire#profil) qu'elle recevra ;
- son environnement (`dev`, `staging` ou `prod`) : celui de l'inviteur, déduit de sa session ou de sa clé API, jamais fourni dans la requête ;
- facultativement, les équipes qu'elle rejoindra et son niveau dans chacune ;
- un jeton de 64 caractères hexadécimaux et une date d'expiration.

Une invitation n'est pas un compte : tant qu'elle n'est pas acceptée, rien n'existe dans Keycloak.

## Comment ça marche

```mermaid
stateDiagram-v2
  [*] --> PENDING: envoi
  PENDING --> ACCEPTED: acceptation
  PENDING --> EXPIRED: consultée après l'échéance
  PENDING --> CANCELLED: annulation
  EXPIRED --> PENDING: relance
  CANCELLED --> PENDING: relance
  ACCEPTED --> [*]
```

| Statut | Signification |
|---|---|
| `PENDING` | Envoyée, en attente. Le lien fonctionne. |
| `ACCEPTED` | Acceptée : le compte existe. Statut définitif. |
| `EXPIRED` | L'échéance est passée. Une invitation passe à ce statut quand elle est consultée ou présentée après sa date d'expiration. |
| `CANCELLED` | Annulée par un administrateur. Le lien ne fonctionne plus. |

Une relance génère un **nouveau jeton** et une nouvelle échéance : l'ancien lien cesse de fonctionner. Une invitation acceptée ne peut être ni relancée ni annulée.

### Contrôles à l'envoi

Wakastart refuse l'invitation si :

1. les invitations sont désactivées pour l'application ;
2. l'auteur a atteint sa limite d'invitations sur 30 jours, si l'application en fixe une ;
3. la vérification des adresses est activée et l'adresse est invalide ou jetable ;
4. un utilisateur existe déjà avec cette adresse, ou une invitation est déjà en attente pour elle, dans ce client **et dans cet environnement** (une fiche en prod n'empêche pas d'inviter la même personne en dev, et inversement) ;
5. une équipe est demandée alors que l'auteur n'en est pas membre avec un niveau au moins égal ;
6. le realm du réseau n'est pas prêt sur l'instance Keycloak de l'environnement de l'inviteur ;
7. la requête fournit un environnement (`envType`, `env` ou `envs`) : il est refusé en `400`.

Avec une [clé API](/v1.0/glossaire#clé-api), l'environnement de l'invitation est celui de la clé ; avec un jeton, celui de la session de l'inviteur.

### L'e-mail

Wakastart envoie l'e-mail dans la langue demandée (`fr` par défaut ; aussi `en`, `es`, `de`, `nl`, `it`, `pt`), depuis le compte d'envoi de l'application ou, à défaut, celui de Wakastart. Le lien pointe vers l'**URL d'acceptation des invitations** de l'application, où le marqueur `{token}` est remplacé par le jeton. Sans marqueur, le jeton est ajouté en paramètre `?token=`.

### L'acceptation

À l'acceptation, Wakastart crée le compte Keycloak sur l'instance de l'environnement de l'invitation, crée la fiche utilisateur dans cet environnement seulement, au niveau **Utilisateur** (`USER`), lui attribue le profil et les équipes prévus, ouvre son accès à l'application, puis Keycloak lui envoie l'e-mail de définition du mot de passe. Une fiche que la personne aurait dans un autre environnement n'est ni lue ni modifiée. Si l'application l'a demandé, l'auteur de l'invitation est prévenu par e-mail.

## Exemples

- **Arrivée d'un collaborateur.** L'administrateur du client, connecté en prod, invite `marie.dupont@cabinet-exemple.fr` avec le profil « Secrétariat ». Elle reçoit l'e-mail, accepte, choisit son mot de passe.
- **Lien perdu.** La personne a laissé passer l'échéance : l'administrateur relance l'invitation, un nouveau lien part.
- **Erreur de destinataire.** L'invitation est partie vers une mauvaise adresse : l'administrateur l'annule avant qu'elle soit acceptée.

## Pour aller plus loin

- [Configurer les invitations](/v1.0/utilisateurs/configurer-les-invitations)
- [Inviter un utilisateur](/v1.0/utilisateurs/inviter-un-utilisateur)
- [Intégrer l'acceptation d'une invitation](/v1.0/utilisateurs/integrer-l-acceptation-d-une-invitation)
