Modules

API Invitations — Création

Créer une invitation : prérequis, endpoint POST /api/invitations, body, réponse et gestion d'erreurs.

Version v1.04 min de lecture

API Invitations — Création

L'API Invitations permet à votre Wakapp d'inviter des utilisateurs à rejoindre un Customer. WakaStart gère l'envoi email, la création du compte Keycloak et le provisioning des droits.

Pré-requis

Feature invitation activée en cascade (App ∧ Network ∧ Customer)
Droit invitations.create sur le token ou la clé API
userLevel >= INVITE pour l'inviteur
Optionnel : App.acceptInvitationUrl configurée pour personnaliser l'URL dans l'email

Cycle de vie d'une invitation

Chargement du diagramme…

Statut	Description
`PENDING`	Créée, en attente d'acceptation
`ACCEPTED`	L'invité a finalisé son compte
`EXPIRED`	Délai dépassé (10 jours par défaut)
`CANCELLED`	Révoquée par l'inviteur

Flux d'invitation complet

Chargement du diagramme…

Endpoint — Créer une invitation

http
POST /api/invitations
Authorization: Bearer <wakaToken>
Content-Type: application/json

{
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "invitedEmail": "alice@acme.com",
  "invitedFirstName": "Alice",
  "invitedLastName": "Martin",
  "profileId": "22222222-2222-2222-2222-222222222222",
  "teamAssignments": [
    { "teamId": "33333333-3333-3333-3333-333333333333", "teamLevel": "MEMBER" }
  ],
  "message": "Bienvenue sur notre application !",
  "language": "fr"
}

Champs du body :

Champ	Type	Requis	Description
`customerId`	UUID	Oui	Customer cible
`invitedEmail`	string	Oui	Email (lowercase appliqué automatiquement)
`invitedFirstName`	string (max 100)	Non	Pré-remplit le compte
`invitedLastName`	string (max 100)	Non	Pré-remplit le compte
`profileId`	UUID	Oui	Profil à attribuer (détermine les droits)
`teamAssignments`	array	Non	Équipes à rejoindre
`message`	string	Non	Message personnalisé dans l'email
`language`	string	Non	`fr`, `en`, `es`, `de`, `nl`, `it`, `pt` (défaut: `fr`)

Réponse 201 :

json
{
  "id": "uuid",
  "customerId": "uuid",
  "invitedEmail": "alice@acme.com",
  "status": "PENDING",
  "token": "a3f8c2d1e4b7...",
  "expiresAt": "2026-05-29T10:30:00.000Z",
  "createdAt": "2026-05-19T10:30:00.000Z",
  "inviter": { "firstName": "Bob", "lastName": "Smith", "email": "bob@..." },
  "profile": { "name": "Participant", "app": { "name": "MonApp" } }
}

Erreurs :

Code	Cause
`400`	Email invalide ou jetable (yopmail, etc.)
`400`	Team assignment référence une team d'un autre Customer
`403`	Droit `invitations.create` absent, `userLevel < INVITE`, ou feature désactivée
`404`	Customer ou Profile introuvable
`409`	Utilisateur avec cet email existe déjà dans ce Customer
`409`	Invitation `PENDING` existe déjà pour cet email + Customer

Endpoints de gestion

Lister les invitations

http
GET /api/invitations/sent                          # Par l'utilisateur courant
GET /api/invitations/sent/app/:appId               # Filtrées par App
GET /api/invitations/by-customer/:customerId       # Toutes pour un Customer

Query params : status, page (défaut 1), limit (défaut 20)

Renvoyer une invitation

http
POST /api/invitations/:id/resend

Génère un nouveau token, réinitialise expiresAt à +10 jours, renvoie l'email. L'ancien token est immédiatement invalide.

Utilisable sur les invitations PENDING ou EXPIRED.

Révoquer une invitation

http
DELETE /api/invitations/:id

Passe l'invitation en CANCELLED. Réponse 204 No Content. Droit requis : invitations.revoke.

Exemple curl

bash
# Créer l'invitation depuis votre backend
curl -X POST https://api.wakastart.app/api/invitations \
  -H "x-api-key: sk_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "11111111-1111-1111-1111-111111111111",
    "invitedEmail": "alice@acme.com",
    "invitedFirstName": "Alice",
    "profileId": "22222222-2222-2222-2222-222222222222",
    "language": "fr"
  }'
# → 201 : invitation créée, email envoyé automatiquement

Bonnes pratiques

Idempotence côté création : si un appel échoue après création (réseau), retenter lèvera un 409 Conflict — c'est sûr, l'invitation existante est toujours valide.
Ne jamais logger le token d'invitation — c'est un secret permettant de créer un compte.
Pré-remplir invitedFirstName/LastName quand possible — meilleure UX.
Gérer les 4 états d'erreur avec des messages explicites adaptés.

Aller plus loin

Invitations — Vérification & Acceptation : verify, accept, lifecycle complet
Feature flags : activation de la feature invitations
Erreurs métier : codes 409 et messages métier