# Intégrer l'acceptation d'une invitation

> Construire dans votre application la page qui reçoit le lien d'invitation, vérifie le jeton et crée le compte de la personne invitée.

Le lien de l'e-mail d'invitation ouvre une page de votre application, à l'adresse que vous avez indiquée dans l'**URL d'acceptation des invitations**. Cette page vérifie le jeton, présente l'invitation, puis la fait accepter. Le mot de passe est ensuite défini dans Keycloak, par e-mail.

## Avant de commencer

- L'**URL d'acceptation des invitations** de l'application pointe vers votre page, par exemple `https://mon-app.exemple.fr/invitation/{token}` : voir [Configurer les invitations](/v1.0/utilisateurs/configurer-les-invitations).
- Les deux endpoints utilisés sont publics : aucun jeton ni clé n'est nécessaire. Appelez-les depuis le serveur de votre application, qui relaie la réponse à la page. Ils acceptent 60 requêtes par seconde, 600 par minute et 5 000 par heure par adresse IP.

## Le déroulé

1. La personne ouvre `https://mon-app.exemple.fr/invitation/<jeton>`.
2. Votre serveur vérifie le jeton.
3. La page affiche l'invitation et un bouton de confirmation.
4. Au clic, votre serveur accepte l'invitation.
5. La page invite la personne à ouvrir l'e-mail « définir votre mot de passe », puis à se connecter.

## Vérifier le jeton

::endpoint{method="GET" path="/api/invitations/verify/{token}"}

Le jeton fait exactement 64 caractères hexadécimaux en minuscules ; sinon l'API répond 400 « Invalid invitation token format ». Pour tout jeton bien formé, la réponse est 200, que l'invitation soit valide ou non.

```bash
curl "https://api.wakastart.app/api/invitations/verify/9f2c4e6a8b0d1f3e5a7c9b1d3f5e7a9c0b2d4f6e8a0c2e4b6d8f0a2c4e6b8d0f"
```

```ts
type VerifyResult = {
  valid: boolean;
  errorMessage?: string;
  invitation?: {
    invitedEmail: string;
    invitedFirstName?: string;
    invitedLastName?: string;
    envType: "dev" | "staging" | "prod";
    expiresAt: string;
    customer: { wid: string; name: string };
    profile: { name: string; app: { name: string } };
  };
};

export async function verifyInvitation(token: string): Promise<VerifyResult> {
  const response = await fetch(
    `https://api.wakastart.app/api/invitations/verify/${encodeURIComponent(token)}`,
  );
  if (response.status === 400) {
    return { valid: false, errorMessage: "Lien d'invitation invalide" };
  }
  return response.json();
}
```

Réponse attendue pour une invitation valide (extrait) :

```json
{
  "valid": true,
  "invitation": {
    "invitedEmail": "marie.dupont@cabinet-exemple.fr",
    "invitedFirstName": "Marie",
    "envType": "prod",
    "expiresAt": "2026-11-02T09:30:00.000Z",
    "customer": { "wid": "Cu9pL2", "name": "Cabinet Exemple" },
    "profile": { "name": "Secrétariat", "app": { "name": "Mon App" } }
  }
}
```

Pour une invitation inutilisable, `valid` vaut `false` et `errorMessage` donne la raison : « Invitation non trouvée », « Cette invitation a déjà été acceptée », « Cette invitation a expiré » ou « Cette invitation a été annulée ». Affichez ce message et proposez de contacter l'administrateur qui a invité.

:::warning
La réponse de vérification contient des informations sur le client et l'invitation. Ne l'affichez qu'à la personne qui détient le lien, et ne la journalisez pas.
:::

## Accepter l'invitation

::endpoint{method="POST" path="/api/invitations/accept/{token}"}

Envoyez un corps JSON vide. Tout champ inconnu (prénom, nom…) est refusé avec une erreur 400 : le prénom et le nom viennent de l'invitation, et le mot de passe se définit dans Keycloak.

```bash
curl -X POST "https://api.wakastart.app/api/invitations/accept/9f2c4e6a8b0d1f3e5a7c9b1d3f5e7a9c0b2d4f6e8a0c2e4b6d8f0a2c4e6b8d0f" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```ts
export async function acceptInvitation(token: string) {
  const response = await fetch(
    `https://api.wakastart.app/api/invitations/accept/${encodeURIComponent(token)}`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({}),
    },
  );
  const body = await response.json();
  if (!response.ok) {
    // 400 : invitation expirée, annulée ou déjà acceptée
    throw new Error(body.message);
  }
  return body as {
    user: { wid: string; email: string; envType: "dev" | "staging" | "prod" };
    provisioning: { status: "full" | "partial"; passwordResetEmail: "sent" | "failed" };
    warnings: string[];
  };
}
```

Réponse attendue (201, extrait) :

```json
{
  "user": { "wid": "Us8hJ4", "email": "marie.dupont@cabinet-exemple.fr", "envType": "prod" },
  "provisioning": {
    "status": "full",
    "keycloakUser": "created",
    "userAppLink": "ok",
    "keycloakOrg": "ok",
    "keycloakGroup": "ok",
    "passwordResetEmail": "sent"
  },
  "warnings": []
}
```

La fiche et son compte Keycloak sont créés dans l'environnement de l'invitation (`user.envType`), et seulement dans celui-là. Le `wid` renvoyé est celui de cette fiche : si la personne a aussi une fiche dans un autre environnement, elle y garde un WID différent.

Si `provisioning.status` vaut `partial`, le compte est créé mais une étape secondaire a échoué ; `warnings` la décrit. Transmettez ce contenu au support Wakastart si l'utilisateur ne parvient pas à se connecter.

## Afficher la suite

Après une acceptation réussie, affichez par exemple : « Votre compte est créé. Ouvrez l'e-mail que vous venez de recevoir pour choisir votre mot de passe, puis connectez-vous. » Le bouton de connexion lance le parcours de connexion habituel de votre application : voir [Authentification](/v1.0/authentification).

Si `passwordResetEmail` vaut `failed`, l'e-mail n'est pas parti : demandez à l'administrateur de contacter le support.

## Vérifier le résultat

- Une seconde vérification du même jeton renvoie `"valid": false` et « Cette invitation a déjà été acceptée ».
- L'invitation apparaît au statut `ACCEPTED` dans `GET /api/invitations/by-customer/{customerWid}`.
- La personne se connecte à votre application après avoir choisi son mot de passe.

## Voir aussi

- [Cycle de vie d'une invitation](/v1.0/utilisateurs/cycle-de-vie-d-une-invitation)
- [Résoudre les problèmes d'utilisateurs](/v1.0/utilisateurs/depannage)
