Invitations
Inviter un utilisateur par e-mail, suivre, relancer et annuler ses invitations, puis vérifier et accepter un lien d'invitation.
This page has not been translated yet and is shown in French.
Une invitation envoie un e-mail contenant un lien unique. En l'acceptant, la personne invitée obtient une fiche dans le client, dans l'environnement de l'invitation, avec le profil et les équipes prévus. Cet environnement est celui de l'inviteur : sa session (claim wenv du jeton) ou sa clé API. Il n'est jamais fourni dans la requête. Le lien pointe vers l'adresse d'acceptation configurée pour votre application, qui appelle ensuite les endpoints publics de vérification et d'acceptation.
Cycle de vie
Une invitation expire après le nombre de jours réglé pour l'application, 10 par défaut (de 1 à 365). Le passage à EXPIRED a lieu quand le lien est vérifié ou accepté après l'échéance. Une relance génère un nouveau lien et une nouvelle échéance.
L'objet Invitation
| Champ | Type | Description |
|---|---|---|
id | UUID | Identifiant |
customerId | UUID | Client dans lequel l'utilisateur sera créé |
invitedEmail | chaîne | E-mail de la personne invitée |
invitedFirstName, invitedLastName | chaîne (100) ou null | Prénom et nom proposés |
profileId | UUID ou null | Profil attribué à l'acceptation (désigné à la création par son WID, profileWid) |
teamAssignments | tableau | Équipes à l'acceptation : { teamId, teamLevel } |
envType | chaîne | Environnement de l'invitation, celui de l'inviteur : dev, staging ou prod. La fiche et son compte Keycloak y sont créés à l'acceptation |
language | chaîne (5) | Langue de l'e-mail, fr par défaut |
message | chaîne ou null | Message personnel ajouté à l'e-mail |
status | chaîne | PENDING, ACCEPTED, EXPIRED ou CANCELLED |
invitedBy | UUID ou null | Auteur ; null si l'invitation a été créée par une clé API sans utilisateur |
expiresAt | chaîne ISO 8601 | Échéance |
acceptedAt | chaîne ISO 8601 ou null | Date d'acceptation |
createdAt | chaîne ISO 8601 | Date de création |
Warning
Le détail d'une invitation contient son jeton, qui suffit à l'accepter. Ne l'exposez jamais à un autre utilisateur que la personne invitée.
Inviter un utilisateur
/api/invitationsDroit requis : invitations.create. L'inviteur doit être au moins Administrateur client du client visé.
| Champ | Type | Obligatoire | Contraintes | Description |
|---|---|---|---|---|
invitedEmail | chaîne | oui | E-mail valide | Adresse de la personne invitée |
customerId | UUID ou WID | oui | — | Client de destination. L'ancien champ customerWid reste accepté mais il est déprécié ; n'envoyez jamais les deux |
profileWid ou profileId | WID ou UUID | non, l'un des deux au plus | — | Profil attribué ; préférez le WID, identifiant public du profil |
invitedFirstName, invitedLastName | chaîne | non | 100 caractères au plus | |
teamAssignments | tableau | non | { teamId | teamWid, teamLevel } | Équipes. Un inviteur humain doit être membre de l'équipe, avec un niveau au moins égal |
language | chaîne | non | 5 caractères au plus | Langue de l'e-mail |
message | chaîne | non | — | Message personnel |
fromName | chaîne | non | 100 caractères au plus | Nom d'expéditeur affiché |
fromEmail | chaîne | non | Adresse d'expéditeur |
curl -s -X POST https://api.wakastart.app/api/invitations \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"invitedEmail": "chloe@clinique-exemple.fr",
"invitedFirstName": "Chloé",
"customerId": "EXCLI1",
"profileWid": "EXPRO2",
"teamAssignments": [{ "teamWid": "EXTEA1", "teamLevel": "MEMBER" }],
"language": "fr"
}'Réponse 201 : l'objet Invitation, au statut PENDING. L'e-mail part depuis le compte d'envoi de l'application s'il est configuré pour cet environnement, sinon depuis celui de Wakastart (voir E-mails).
Erreurs
| Statut | Message |
|---|---|
400 | Fournir exactement un des champs customerId ou customerWid |
400 | Email invalide ou Les emails jetables ne sont pas autorisés |
400 | Environment is deduced from the caller and cannot be provided : envType, env ou envs envoyé |
400 | Le realm du network n'est pas provisionné sur l'instance '<env>'. … : environnement de l'inviteur |
403 | Vous devez avoir au minimum le niveau CUSTOMER_ADMIN pour inviter des utilisateurs |
403 | La fonctionnalité invitation n'est pas activée pour ce customer |
403 | Limite d'invitations atteinte (<n> par mois). Réessayez plus tard. |
403 | Vous n'êtes pas membre de la team <nom> |
404 | Customer with WID <wid> not found, Profile with WID <wid> not found, Team with WID <wid> not found |
409 | Un utilisateur avec cet email existe déjà : fiche existante chez ce client, dans l'environnement de l'inviteur |
409 | Une invitation est déjà en cours pour cet email : invitation PENDING chez ce client, dans l'environnement de l'inviteur |
500 | La création de l'invitation a échoué à l'envoi de l'email |
Lister ses invitations
/api/invitations/sent/api/invitations/sent/app/{appId}Droit requis : invitations.read. Renvoie les invitations envoyées par l'appelant, toutes applications confondues ou pour une application (appId : UUID).
| Paramètre de requête | Type | Défaut | Description |
|---|---|---|---|
page | entier ≥ 1 | 1 | Page |
limit | entier, 1 à 100 | 20 | Taille de page |
status | chaîne | — | PENDING, ACCEPTED, EXPIRED ou CANCELLED |
curl -s "https://api.wakastart.app/api/invitations/sent?status=PENDING" \
-H "Authorization: Bearer $ACCESS_TOKEN"Réponse : { "data": [Invitation…], "meta": { "page", "limit", "total", "totalPages" } }.
Lister les invitations d'un client
/api/invitations/by-customer/{customerId}Droit requis : invitations.read. customerId : UUID ou WID de votre client. Mêmes paramètres et même réponse que la liste précédente.
Erreurs : 403 Customer <id> is outside the caller's tenant scope.
Lire une invitation
/api/invitations/{id}Droit requis : invitations.read. Réponse : l'objet Invitation. 404 Invitation with ID <id> not found.
Relancer une invitation
/api/invitations/{id}/resendDroit requis : invitations.create. Génère un nouveau lien et une nouvelle échéance, renvoie l'e-mail et repasse l'invitation en PENDING, y compris depuis EXPIRED ou CANCELLED. L'auteur et les administrateurs du client peuvent relancer.
Erreurs : 400 Cette invitation a déjà été acceptée ; 403 Vous ne pouvez pas renvoyer cette invitation ; 500 Le renvoi de l'invitation a échoué à l'envoi de l'email.
Annuler une invitation
/api/invitations/{id}Droit requis : invitations.revoke. Passe l'invitation en CANCELLED : le lien ne fonctionne plus.
Erreurs : 400 Cette invitation a déjà été acceptée ; 403 Vous ne pouvez pas annuler cette invitation.
Vérifier un lien d'invitation
/api/invitations/verify/{token}Accès : public. À appeler depuis la page d'acceptation de votre application, avant d'afficher le formulaire.
| Paramètre | Où | Contraintes |
|---|---|---|
token | chemin | Exactement 64 caractères hexadécimaux minuscules, tel que reçu dans le lien |
curl -s https://api.wakastart.app/api/invitations/verify/3b1f0c9a8e7d6c5b4a39281706f5e4d3c2b1a0f9e8d7c6b5a4938271605f4e3dLa réponse est toujours 200. Invitation valide :
{
"valid": true,
"invitation": {
"id": "7c6b5a49-3333-4f5e-8d7c-6b5a49382716",
"invitedEmail": "chloe@clinique-exemple.fr",
"invitedFirstName": "Chloé",
"status": "PENDING",
"envType": "prod",
"expiresAt": "2026-11-02T10:00:00.000Z"
}
}Invitation inutilisable :
{ "valid": false, "errorMessage": "Cette invitation a expiré" }Valeurs de errorMessage : Invitation non trouvée, Cette invitation a déjà été acceptée, Cette invitation a expiré, Cette invitation a été annulée.
Erreurs : 400 Invalid invitation token format.
Accepter une invitation
/api/invitations/accept/{token}Accès : public. Crée, dans l'environnement de l'invitation et seulement dans celui-là, le compte Keycloak et la fiche utilisateur avec le niveau USER, le profil et les équipes prévus, puis passe l'invitation en ACCEPTED. Une fiche que la personne aurait dans un autre environnement n'est ni lue ni modifiée. Keycloak envoie ensuite à la personne invitée un e-mail pour définir son mot de passe.
L'appel ne demande aucun champ : envoyez un corps JSON vide. Le prénom et le nom viennent de l'invitation ; l'utilisateur peut les modifier plus tard dans son profil.
curl -s -X POST https://api.wakastart.app/api/invitations/accept/3b1f0c9a8e7d6c5b4a39281706f5e4d3c2b1a0f9e8d7c6b5a4938271605f4e3d \
-H 'Content-Type: application/json' \
-d '{}'Réponse 201
{
"user": { "wid": "EXUSR5", "email": "chloe@clinique-exemple.fr", "adminLevel": "USER", "envType": "prod" },
"provisioning": {
"status": "full",
"keycloakUser": "created",
"userAppLink": "ok",
"keycloakOrg": "ok",
"keycloakGroup": "skipped",
"passwordResetEmail": "sent"
},
"warnings": []
}user reprend les champs de l'objet Utilisateur ; l'exemple n'en montre qu'une partie. provisioning.status vaut partial si une étape secondaire a échoué : accès à l'application (userAppLink), organisation ou groupe Keycloak (keycloakOrg, keycloakGroup), envoi de l'e-mail de mot de passe (passwordResetEmail à failed). warnings en donne le détail. Le compte existe dans les deux cas.
Erreurs : 400 Invalid invitation token format ; 400 Cette invitation a expiré, Cette invitation a déjà été acceptée, Cette invitation a été annulée ou Invitation invalide ; 500 Impossible d'envoyer l'email de définition du mot de passe : <détail>. L'invitation a été restaurée, l'utilisateur peut réessayer.
Les deux endpoints publics ont leur propre limite de débit : 60 requêtes par seconde, 600 par minute et 5 000 par heure par adresse IP.