Documentation

Authentification et clés

Clé serveur ou clé widget, origines autorisées, sessions visiteur et utilisateurs finaux : quelle clé utiliser, et où.

Chaque appel au hub (Gaspard et les autres produits) est authentifié par la clé d’une application (un « client » de l’API), créée et configurée pour vous par l’équipe HubMix, qui vous remet sa clé (faire une demande). Il existe deux sortes d’applications, donc deux sortes de clés. Une clé n’ouvre que les produits choisis pour son application.

	Clé serveur (secrète)	Clé widget (publiable)
Préfixe	`vck_live_…`	`vcp_live_…`
Où	Votre backend uniquement	Navigateur, application mobile
En-tête	`Authorization: Bearer vck_live_…`	`X-Gaspard-Key: vcp_live_…`
Limitée à	—	Les origines déclarées pour le client
Consentement	Vous le recueillez et l’enregistrez	Une session visiteur, après accord à l’avis
Exemples	Laravel, Node.js, ASP.NET Core, Spring, Ktor	Widget, WordPress, Flutter, Android

La clé vous est remise une seule fois ; le service n’en garde qu’une empreinte. Chaque client peut avoir jusqu’à 3 clés actives, ce qui permet de remplacer une clé sans interruption.

Depuis votre serveur #

HTTP

POST /v1/public/gaspard/conversations HTTP/1.1
Host: hubmix.dealmood-solutions.com
Authorization: Bearer vck_live_…
X-End-User: user-42
Content-Type: application/json

{"locale": "fr"}

Vos utilisateurs : `X-End-User` #

Avec une clé serveur, indiquez qui pose la question avec X-End-User (l’identifiant de la personne dans votre application, 1 à 128 caractères ASCII imprimables). Le service n’en garde qu’un hachage à clé : il ne connaît jamais l’identifiant lui-même. Chaque personne :

ne voit que ses propres conversations ;
a son propre consentement (PUT /visitors/me/consent, après lui avoir montré l’avis de GET /privacy-notice) ;
peut exporter (GET /visitors/me/data) ou effacer (DELETE /visitors/me) ses données.

Les SDK le font avec forEndUser(id) (ou withEndUser en PHP) : un client dérivé, sans modifier le client partagé.

Depuis un navigateur ou une app #

Une clé widget est faite pour être visible : elle ne fonctionne que depuis les origines autorisées déclarées pour le client (jusqu’à 20, par exemple https://www.mon-site.ch et https://mon-site.ch, sans chemin).

Lisez l’avis : GET /privacy-notice avec X-Gaspard-Key.
Montrez-le au visiteur. S’il accepte, ouvrez une session : POST /sessions avec {"consent": true, "locale": "fr", "allow_training": false}.
Gardez le jeton token (vst_…, valable 30 jours) et envoyez-le ensuite avec la clé : Authorization: Bearer vst_….

Le navigateur envoie lui-même l’en-tête Origin. Une application native (Flutter, Android, .NET MAUI) doit l’envoyer elle-même : c’est l’option origin des SDK, qui doit correspondre à l’une des origines déclarées (par exemple https://app.mon-ecole.ch).

Le widget et les SDK font toutes ces étapes pour vous.

Clé interne de l’app Valais Connect #

Le service connaît aussi une clé interne (X-Internal-Api-Key), réservée au backend de l’application Valais Connect elle-même. Elle n’est jamais délivrée aux développeurs, n’apparaît dans aucun SDK et ne doit jamais être demandée par une intégration tierce.

Scopes #

Les clients de l’offre gratuite ont deux scopes :

Scope	Permet
`assistant:public`	Conversations, questions, notes, consentement et droits des personnes
`knowledge:search`	`POST /knowledge/search`

Une route hors des scopes du client répond 403 insufficient_scope.

Erreurs d’authentification #

Statut	Code	Cause
`401`	`unauthenticated`	Clé absente, inconnue, révoquée ou expirée
`401`	`session_required` / `invalid_visitor_token`	Clé widget sans jeton visiteur valide : ouvrez une session
`403`	`origin_not_allowed`	L’origine n’est pas déclarée pour ce client
`403`	`consent_required`	Le visiteur n’a pas accepté l’avis en vigueur (ou a retiré son accord)
`403`	`client_suspended`	Client suspendu par l’équipe HubMix
`422`	`invalid_end_user`	`X-End-User` mal formé

Les messages ne disent jamais quelle partie d’une clé est fausse. La liste complète des codes : Erreurs, limites et quotas.