Invitations

Le modèle d'invitation en détail, de l'API d'administration au lien d'activation, avec la revalidation du rôle à l'acceptation, l'expiration et la révocation.

L'annuaire d'Obexal fonctionne sur un modèle d'invitation : c'est l'acceptation de l'invitation qui crée et active le compte. Cette page est la référence complète ; pour le parcours guidé, commencez par Inviter votre équipe.

Invitation égale activation

L'auto-inscription est désactivée par défaut (fail-closed : désactivée aussi si le réglage est illisible), donc l'annuaire ne contient que des comptes explicitement invités ou provisionnés. Une invitation est nominative (liée à une seule adresse e-mail), à usage unique, et vaut vérification d'e-mail : le compte activé démarre avec une adresse vérifiée, car le lien lui-même prouve le contrôle de la boîte.

Si votre cas d'usage exige l'inscription ouverte, un admin peut la réactiver par organisation : le réglage de la console correspond à branding.allowSelfSignup sur PATCH /v1/admin/tenant.

Créer une invitation

POST /v1/admin/invitations (permission de gestion des membres, session ou jeton d'API admin) :

curl -sS -X POST https://accounts.obexal.com/v1/admin/invitations \
  -H "Authorization: Bearer $OBEXAL_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"email":"alice@example.eu","role":"member","givenName":"Alice","familyName":"Martin"}'
# 202 -> {"status":"ok"}   (événement d'audit : admin.invitation.created)

Champ	Requis	Signification
`email`	oui	L'adresse de l'invité ; seule cette adresse exacte peut activer l'invitation
`role`	oui	Un rôle système (`owner`, `admin`, `member`) ou la clé d'un rôle personnalisé
`givenName`	non	Pré-remplit le profil à l'activation
`familyName`	non	Pré-remplit le profil à l'activation

À la création, la garde anti-escalade du RBAC s'applique : vous ne pouvez accorder qu'un rôle dont les permissions sont un sous-ensemble des vôtres, et seul un owner peut inviter un owner. Une seule invitation en attente peut exister par adresse : la réinviter renvoie 409. Le token d'invitation est aléatoire (32 octets) ; seul son hachage SHA-256 est stocké.

Le lien d'activation

L'invité reçoit un e-mail pointant vers https://accounts.obexal.com/accept-invite?token=... (votre domaine personnalisé remplace le domaine par défaut). La page appelle l'endpoint public :

curl -sS -X POST https://accounts.obexal.com/v1/auth/accept-invite \
  -H 'Content-Type: application/json' \
  -d "{\"token\":\"$INVITE_TOKEN\",\"password\":\"$NEW_PASSWORD\",\"givenName\":\"Alice\",\"familyName\":\"Martin\"}"
# 200 -> {"user":{...},"redirectUrl":"/dashboard"}   (cookie de session posé : connexion automatique)

L'invité choisit un mot de passe (validé contre la politique de mot de passe de l'organisation, 12 caractères minimum par défaut), peut poser ou compléter son prénom et son nom (sa saisie prime sur le pré-remplissage de l'admin), et se retrouve connecté automatiquement sur le portail « Mes applications ». Cas d'erreur : 400 invalid_invite (lien inconnu, révoqué ou expiré), 409 already_active (le compte a déjà un mot de passe : une invitation n'écrase jamais des identifiants), 400 invalid_request (mot de passe refusé par la politique), 429 rate_limited.

Il existe aussi un chemin de compatibilité pour un utilisateur déjà connecté à l'organisation : POST /v1/invitations/accept avec {"token":"..."} rattache le rôle de l'invitation au compte existant, à condition que l'e-mail de la session corresponde à l'invitation.

Revalidation du rôle à l'acceptation

Le rôle accordé à l'acceptation n'est pas aveuglément celui stocké à la création. Entre les deux moments, l'invitant a pu être rétrogradé ou retiré, ou un rôle personnalisé supprimé. Obexal revalide donc l'autorité actuelle de l'invitant au moment où le lien est utilisé : le rôle doit toujours exister, et ses permissions doivent toujours être un sous-ensemble des permissions de l'invitant à cet instant (owner reste réservé aux owners). Si l'un des deux contrôles échoue, l'invité rejoint l'organisation comme member (fail-closed).

Note

Cela ferme l'écart classique entre le moment du contrôle et le moment de l'usage (TOCTOU) : une invitation en attente ne peut jamais conférer un privilège qui survit à la perte d'autorité de son émetteur.

Expiration et révocation

Les invitations expirent après 7 jours par défaut. GET /v1/admin/invitations les liste avec status (pending, accepted, revoked), expiresAt, createdAt et, le cas échéant, acceptedAt.

curl -sS -X DELETE https://accounts.obexal.com/v1/admin/invitations/<id> \
  -H "Authorization: Bearer $OBEXAL_API_TOKEN"
# 200 -> {"status":"ok"}   (événement d'audit : admin.invitation.revoked)

Un lien révoqué ou expiré cesse de fonctionner immédiatement (invalid_invite). Il n'y a pas d'action de renvoi distincte : révoquez l'invitation en attente puis réinvitez l'adresse pour générer un nouveau lien. L'acceptation est auditée comme admin.invitation.accepted, avec le rôle réellement accordé.