Aller au contenu

Invitations

Inviter un utilisateur par e-mail, suivre, relancer et annuler ses invitations, puis vérifier et accepter un lien d'invitation.

RéférenceDéveloppeurAdministrateur
Voir en Markdown

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

Chargement du schéma…

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

ChampTypeDescription
idUUIDIdentifiant
customerIdUUIDClient dans lequel l'utilisateur sera créé
invitedEmailchaîneE-mail de la personne invitée
invitedFirstName, invitedLastNamechaîne (100) ou nullPrénom et nom proposés
profileIdUUID ou nullProfil attribué à l'acceptation (désigné à la création par son WID, profileWid)
teamAssignmentstableauÉquipes à l'acceptation : { teamId, teamLevel }
envTypechaîneEnvironnement de l'invitation, celui de l'inviteur : dev, staging ou prod. La fiche et son compte Keycloak y sont créés à l'acceptation
languagechaîne (5)Langue de l'e-mail, fr par défaut
messagechaîne ou nullMessage personnel ajouté à l'e-mail
statuschaînePENDING, ACCEPTED, EXPIRED ou CANCELLED
invitedByUUID ou nullAuteur ; null si l'invitation a été créée par une clé API sans utilisateur
expiresAtchaîne ISO 8601Échéance
acceptedAtchaîne ISO 8601 ou nullDate d'acceptation
createdAtchaîne ISO 8601Date de création

Attention

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

POST/api/invitations

Droit requis : invitations.create. L'inviteur doit être au moins Administrateur client du client visé.

ChampTypeObligatoireContraintesDescription
invitedEmailchaîneouiE-mail valideAdresse de la personne invitée
customerIdUUID ou WIDoui—Client de destination. L'ancien champ customerWid reste accepté mais il est déprécié ; n'envoyez jamais les deux
profileWid ou profileIdWID ou UUIDnon, l'un des deux au plus—Profil attribué ; préférez le WID, identifiant public du profil
invitedFirstName, invitedLastNamechaînenon100 caractères au plus
teamAssignmentstableaunon{ teamId | teamWid, teamLevel }Équipes. Un inviteur humain doit être membre de l'équipe, avec un niveau au moins égal
languagechaînenon5 caractères au plusLangue de l'e-mail
messagechaînenon—Message personnel
fromNamechaînenon100 caractères au plusNom d'expéditeur affiché
fromEmailchaînenonE-mailAdresse d'expéditeur
Bash
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

StatutMessage
400Fournir exactement un des champs customerId ou customerWid
400Email invalide ou Les emails jetables ne sont pas autorisés
400Environment is deduced from the caller and cannot be provided : envType, env ou envs envoyé
400Le realm du network n'est pas provisionné sur l'instance '<env>'. … : environnement de l'inviteur
403Vous devez avoir au minimum le niveau CUSTOMER_ADMIN pour inviter des utilisateurs
403La fonctionnalité invitation n'est pas activée pour ce customer
403Limite d'invitations atteinte (<n> par mois). Réessayez plus tard.
403Vous n'êtes pas membre de la team <nom>
404Customer with WID <wid> not found, Profile with WID <wid> not found, Team with WID <wid> not found
409Un utilisateur avec cet email existe déjà : fiche existante chez ce client, dans l'environnement de l'inviteur
409Une invitation est déjà en cours pour cet email : invitation PENDING chez ce client, dans l'environnement de l'inviteur
500La création de l'invitation a échoué à l'envoi de l'email

Lister ses invitations

GET/api/invitations/sent
GET/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êteTypeDéfautDescription
pageentier ≥ 11Page
limitentier, 1 à 10020Taille de page
statuschaîne—PENDING, ACCEPTED, EXPIRED ou CANCELLED
Bash
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

GET/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

GET/api/invitations/{id}

Droit requis : invitations.read. Réponse : l'objet Invitation. 404 Invitation with ID <id> not found.

Relancer une invitation

POST/api/invitations/{id}/resend

Droit 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

DELETE/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

GET/api/invitations/verify/{token}

Accès : public. À appeler depuis la page d'acceptation de votre application, avant d'afficher le formulaire.

ParamètreOùContraintes
tokencheminExactement 64 caractères hexadécimaux minuscules, tel que reçu dans le lien
Bash
curl -s https://api.wakastart.app/api/invitations/verify/3b1f0c9a8e7d6c5b4a39281706f5e4d3c2b1a0f9e8d7c6b5a4938271605f4e3d

La réponse est toujours 200. Invitation valide :

JSON
{
  "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 :

JSON
{ "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

POST/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.

Bash
curl -s -X POST https://api.wakastart.app/api/invitations/accept/3b1f0c9a8e7d6c5b4a39281706f5e4d3c2b1a0f9e8d7c6b5a4938271605f4e3d \
  -H 'Content-Type: application/json' \
  -d '{}'

Réponse 201

JSON
{
  "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.