Inviter un utilisateur
Envoyer une invitation par l'API publique pour qu'une personne rejoigne un client avec un profil donné, dans l'environnement de l'inviteur.
- Accès requis
- Niveau Administrateur client et droit invitations.create
- Durée
- 10 min
L'invitation est la façon recommandée de faire entrer un utilisateur : la personne reçoit un e-mail, crée son compte elle-même et reçoit d'office le bon profil. Vous envoyez l'invitation depuis le serveur de votre application, ou depuis vos outils d'administration, avec l'API publique.
Avant de commencer
- Les invitations sont activées et l'URL d'acceptation est renseignée : voir Configurer les invitations.
- Vous appelez l'API avec une clé API ou le jeton d'un administrateur. L'appelant a le niveau Administrateur client au moins et le droit
invitations.create. - Vous appelez avec un jeton ou une clé de l'environnement visé : l'invitation appartient à l'environnement de l'inviteur (celui de sa session, ou celui de la clé API), et la fiche sera créée dans cet environnement seulement.
- Vous connaissez le WID du client et celui du profil à attribuer. Les profils disponibles pour un client se listent avec
GET /api/config/profiles/customer/{customerWid}/visible: voir Créer un profil.
Envoyer l'invitation
/api/invitationscurl -X POST "https://api.wakastart.app/api/invitations" \
-H "x-api-key: sk_test_exemple" \
-H "Content-Type: application/json" \
-d '{
"invitedEmail": "marie.dupont@cabinet-exemple.fr",
"invitedFirstName": "Marie",
"invitedLastName": "Dupont",
"customerId": "Cu9pL2",
"profileWid": "Pr5sT1",
"language": "fr",
"message": "Bienvenue dans l'\''espace de votre cabinet."
}'const response = await fetch("https://api.wakastart.app/api/invitations", {
method: "POST",
headers: {
"x-api-key": process.env.WAKASTART_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify({
invitedEmail: "marie.dupont@cabinet-exemple.fr",
invitedFirstName: "Marie",
invitedLastName: "Dupont",
customerId: "Cu9pL2",
profileWid: "Pr5sT1",
language: "fr",
message: "Bienvenue dans l'espace de votre cabinet.",
}),
});
if (!response.ok) {
const error = await response.json();
throw new Error(`Invitation refusée : ${error.message}`);
}
const invitation = await response.json();Réponse attendue (extrait) :
{
"id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"invitedEmail": "marie.dupont@cabinet-exemple.fr",
"status": "PENDING",
"envType": "prod",
"language": "fr",
"expiresAt": "2026-11-02T09:30:00.000Z"
}Wakastart envoie aussitôt l'e-mail d'invitation, avec le lien vers votre page d'acceptation. Le champ envType de la réponse indique l'environnement de l'invitation : ici prod, celui de la clé.
Champs de la requête
| Champ | Obligatoire | Description |
|---|---|---|
invitedEmail | oui | Adresse de la personne invitée |
customerId | oui | Client à rejoindre, par son WID ou son UUID. L'ancien champ customerWid est déprécié : utilisez customerId, et n'envoyez jamais les deux. Un administrateur client ne peut inviter que dans son client. |
profileWid | oui | WID du profil attribué à l'acceptation ; ses droits sont ceux de l'environnement de l'invitation. profileId accepte encore l'UUID ; n'envoyez jamais les deux. |
invitedFirstName, invitedLastName | non | 100 caractères chacun, repris dans l'e-mail |
teamAssignments | non | Équipes à rejoindre : [{ "teamWid": "Tm3qX7", "teamLevel": "MEMBER" }] |
language | non | Langue de l'e-mail : fr (par défaut), en, es, de, nl, it, pt |
message | non | Message personnel ajouté à l'e-mail |
fromEmail, fromName | non | Expéditeur de l'e-mail. L'adresse doit être un expéditeur validé du compte d'envoi. |
Important
N'envoyez pas envType (ni env ou envs) : l'environnement est déduit de l'inviteur, et ces champs sont refusés en 400 (Environment is deduced from the caller and cannot be provided). Pour inviter la même personne dans un autre environnement, envoyez une seconde invitation avec un jeton ou une clé de cet environnement.
Note
Un utilisateur humain qui ajoute des équipes à son invitation doit être membre de chacune avec un niveau au moins égal à celui qu'il attribue. Une clé API technique n'est pas soumise à cette règle.
Vérifier le résultat
- La personne reçoit l'e-mail ; le lien pointe vers votre URL d'acceptation, avec le jeton.
GET /api/invitations/by-customer/Cu9pL2liste l'invitation au statutPENDING. Voir Suivre les invitations.
Dépannage
- « Un utilisateur avec cet email existe déjà » ou « Une invitation est déjà en cours pour cet email » : la personne a déjà une fiche, ou une invitation en attente, chez ce client dans cet environnement. Une fiche dans un autre environnement ne bloque pas l'invitation. Voir Résoudre les problèmes d'utilisateurs.
- « La fonctionnalité invitation n'est pas activée pour ce customer » : cochez Activer les invitations dans le paramétrage de l'application.
Invitation déclenchée par un client de votre application
Si l'invitation part d'un organisme client qui appelle votre application avec une clé API de votre application, prenez le client cible dans l'enregistrement de cette clé, jamais dans la requête reçue, et joignez le jeton de contexte que Wakastart vous fournit. Voir Agir sur Wakastart pour un client.