# Invitations

`POST /api/auth/admin/create-user` oblige un administrateur à choisir le mot de passe du nouvel utilisateur et ne lui envoie rien — praticable pour un script, inutilisable pour accueillir un client. Le flux d'invitation comble cette lacune : l'administrateur fournit `{ email, name, role }` **sans mot de passe**, Sovrium envoie par e-mail un lien à usage unique, et l'invité définit son propre mot de passe puis atterrit dans une session authentifiée.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  invitationTokenExpiry: '72h' # default; accepts '30s' / '15m' / '72h' / '7d' / ms
  emailTemplates:
    invitation:
      subject: 'You are invited to join, $name'
      text: |
        Hi $name,
        $inviterName invited you to join.
        Set your password: $url
        This invitation expires in 72 hours.
```

## Les deux points de terminaison

| Point de terminaison                     | Comportement                                                                                                                                                                                                                                                                    |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /api/auth/admin/invite-user`       | Accepte `{ email, name, role }` (sans mot de passe). Renvoie `200` avec `{ user, invitationSent: true }`. `401`/`403` pour non authentifié / non administrateur ; `400` pour une saisie invalide ; `422` lorsque l'e-mail correspond déjà à un utilisateur entièrement intégré. |
| `POST /api/auth/admin/accept-invitation` | Sous-tend la page publique `/accept-invitation?token=...`. L'invité définit un mot de passe et atterrit authentifié. `400` pour un jeton invalide, `410` pour un jeton expiré.                                                                                                  |

Les jetons réutilisent la table `auth.verification` (la même forme que Better Auth emploie pour la réinitialisation de mot de passe), expirent après [`invitationTokenExpiry`](/fr/docs/auth-registration) — `72h` par défaut — et sont à usage unique, consommés à la première acceptation réussie. Un rejeu est rejeté plutôt que de ré-intégrer silencieusement.

Le corps de l'e-mail est rendu à partir du [modèle](/fr/docs/auth-email-templates) `invitation` et substitue `$name`, `$url`, `$email` et `$inviterName`.

:::callout
**`allowSignUp: false` ne bloque pas les invitations.** Fermer l'auto-inscription publique est précisément le moment où vous avez besoin de ce flux. La création d'utilisateur pilotée par un administrateur reste disponible dès que l'authentification est configurée — voir [Contrôle de l'inscription](/fr/docs/auth-registration).
:::

## Attribution de rôle

Sovrium fournit trois rôles par défaut — `admin`, `member`, `viewer` — de niveaux hiérarchiques 80, 40 et 10, et accepte des rôles personnalisés déclarés dans le bloc `auth`.

Une invitation porte un `role` explicite. Lorsqu'aucun n'est fourni à la création, un nouvel utilisateur reçoit `auth.defaultRole`, qui lui-même retombe sur `member` :

```yaml
auth:
  strategies:
    - type: emailAndPassword
  defaultRole: viewer
  roles:
    - name: editor
      description: Can edit content
      level: 30
```

`defaultRole` est validé contre les rôles intégrés plus vos `roles[]` déclarés : une faute de frappe échoue donc à `sovrium validate` au lieu de n'attribuer discrètement rien. Le premier administrateur d'amorçage est toujours créé avec le rôle `admin` et une adresse vérifiée, quel que soit `defaultRole`.

Les rôles pilotent chaque décision d'autorisation de la plateforme : les [permissions](/fr/docs/table-permissions) de table, l'accès par champ, l'accès aux pages et l'API d'administration elle-même. Un rôle peut être changé après coup via `POST /api/auth/admin/set-role`.

## Invitation ou create-user

| Vous voulez                                           | Utilisez                                                                         |
| ----------------------------------------------------- | -------------------------------------------------------------------------------- |
| Qu'un client choisisse son propre mot de passe        | `invite-user` — il reçoit un lien et ne voit jamais un secret défini par autrui. |
| Un compte de service ou d'amorçage, sans boîte e-mail | `create-user` — vous définissez le mot de passe, rien n'est envoyé.              |
| Accueillir alors que SMTP n'est pas configuré         | `create-user` — un e-mail d'invitation ne serait jamais délivré.                 |

:::callout
**L'accueil est découplé de l'attribution d'accès.** Inviter un utilisateur crée le compte ; cela ne lui accorde aucune portée de locataire. Relier un utilisateur aux données qu'il peut atteindre est une étape distincte via l'API des enregistrements : un administrateur peut donc inviter d'abord et attribuer ensuite, ou l'inverse. Voir [Affectations et gardes d'atterrissage](/fr/docs/auth-assignments).
:::

## Pages connexes

- [Gestion des utilisateurs](/fr/docs/user-management) — amorçage administrateur et API create-user.
- [Contrôle de l'inscription](/fr/docs/auth-registration) — `allowSignUp` et `invitationTokenExpiry`.
- [Rôles & RBAC](/fr/docs/auth-roles-rbac) — le modèle de rôle complet et les permissions par champ.
- [Modèles d'e-mail](/fr/docs/auth-email-templates) — l'objet et le corps de l'e-mail `invitation`.
- [Affectations et gardes d'atterrissage](/fr/docs/auth-assignments) — accorder à un utilisateur sa portée de locataire.