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.
- Accès requis
- Endpoints publics, sans authentification
- Durée
- 20 min
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. - 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é
- La personne ouvre
https://mon-app.exemple.fr/invitation/<jeton>. - Votre serveur vérifie le jeton.
- La page affiche l'invitation et un bouton de confirmation.
- Au clic, votre serveur accepte l'invitation.
- La page invite la personne à ouvrir l'e-mail « définir votre mot de passe », puis à se connecter.
Vérifier le jeton
/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.
curl "https://api.wakastart.app/api/invitations/verify/9f2c4e6a8b0d1f3e5a7c9b1d3f5e7a9c0b2d4f6e8a0c2e4b6d8f0a2c4e6b8d0f"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) :
{
"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é.
Attention
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
/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.
curl -X POST "https://api.wakastart.app/api/invitations/accept/9f2c4e6a8b0d1f3e5a7c9b1d3f5e7a9c0b2d4f6e8a0c2e4b6d8f0a2c4e6b8d0f" \
-H "Content-Type: application/json" \
-d '{}'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) :
{
"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.
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": falseet « Cette invitation a déjà été acceptée ». - L'invitation apparaît au statut
ACCEPTEDdansGET /api/invitations/by-customer/{customerWid}. - La personne se connecte à votre application après avoir choisi son mot de passe.