Authentification

Clés d’API (recommandées pour les intégrations)

Une clé d’API est un jeton d’accès personnel lié à un membre de votre compte.

Créez-en une dans Paramètres → Plugins → Clés d’API RolChat. Le secret n’est affiché qu’une fois ; ensuite, seuls ses dix premiers caractères restent visibles, et RolChat ne stocke qu’un hachage SHA-256.
Format : rcp_ suivi de 32 octets aléatoires en base64url, soit environ 45 caractères au total. Le préfixe rend une clé reconnaissable dans les journaux et la distingue d’un jeton de session.
Portées : choisies dans un catalogue fixe de capacités lors de la création de la clé. Une clé ne peut jamais faire plus que le membre qui l’a créée : à chaque appel, les deux conditions sont vérifiées, la capacité figure dans les portées de la clé et le membre la détient toujours. Restreignez le rôle du membre et la clé est restreinte d’autant.
Durée de vie : les clés n’expirent pas d’elles-mêmes. Révoquez une clé depuis la page de profil ou avec DELETE /api/v1/tokens/:id ; la révocation prend effet immédiatement. Il n’y a pas de renouvellement sur place : révoquez la clé et créez-en une nouvelle.
La création et la révocation sont inscrites dans le journal d’audit.

Envoyez-la comme jeton bearer - il n’existe pas d’en-tête distinct pour les clés d’API :

curl https://api.rolchat.com/api/v1/contacts?limit=20 \
  -H "Authorization: Bearer rcp_…" \
  -H "X-Account-Id: 7c1d2c6e-…"

Les requêtes effectuées avec une clé d’API de plugin sont limitées à 300 par minute.

Sessions JWT

L’application web et les SDK mobiles se connectent avec un e-mail et un mot de passe (ou avec Google ou Apple) et reçoivent une paire de jetons.

Jeton	Durée de vie	Remarques
Jeton d’accès	15 minutes	RS256, vérifié avec le JWKS publié sur `/.well-known/jwks.json`
Jeton de rafraîchissement	30 jours	Remplacé à chaque rafraîchissement ; la réutilisation d’un jeton déjà remplacé révoque toute la chaîne

Claims : sub (utilisateur), acc (compte), rl (rôle) et, pour les rôles par site, sts (sites autorisés).

POST /auth/login, /auth/refresh, /auth/swap-company et /auth/logout sont les seuls endpoints du parcours d’authentification qui ne doivent pas porter l’en-tête X-Account-Id décrit ci-dessous.

L’en-tête `X-Account-Id`

Chaque requête authentifiée, à l’exception des quatre ci-dessus, doit indiquer le compte pour lequel elle agit :

X-Account-Id: <account uuid>

Le serveur vérifie que l’en-tête correspond au claim acc du jeton (ou au compte de la clé d’API). Un en-tête manquant donne 400 missing_required_header ; une non-correspondance donne 403 account_context_mismatch. Cet en-tête existe pour qu’un bug client ou un jeton rejoué ne puisse jamais lire silencieusement les données d’un autre locataire : la non-correspondance est rejetée avant l’exécution de toute requête, et chaque ligne de journal peut être attribuée à un compte sans décoder le jeton.

Utilisateurs de plusieurs entreprises

Une même personne peut appartenir à plusieurs entreprises. Chaque entreprise a son propre jeton (son propre claim acc). Pour changer d’entreprise :

POST /api/v1/auth/swap-company
Authorization: Bearer <current access token>

{ "account_id": "<target uuid>" }

La cible doit faire partie des available_companies de l’appelant (renvoyées à la connexion), sinon la réponse est 403 forbidden. La réponse contient une nouvelle paire de jetons d’accès et de rafraîchissement limitée à la cible ; l’ancien jeton de rafraîchissement est révoqué et un événement d’audit auth.account.swapped est enregistré.