Gérer les clés API

Le canal Widget externe permet d’intégrer un agent REDA AI à un site ou à une application externe. Chaque agent de ce canal utilise une clé API. Ce guide explique sa génération, son remplacement, sa révocation et les contrôles à associer à son utilisation.

Comprendre les clés API

La clé est une valeur aléatoire qui permet au service de retrouver et valider l’agent externe appelé. Elle intervient dans deux domaines :

1. Validation de l’agent : l’appel doit présenter la clé active. Dans un widget public, cette clé est visible dans la page ; elle ne prouve donc pas l’identité d’un visiteur ni celle d’une application de confiance.
2. Suivi et limites d’usage : une fois l’agent identifié, le service applique les contrôles de session, de débit et de crédits prévus pour le parcours.

Un agent Widget externe possède une seule clé active à la fois. Plusieurs agents peuvent disposer chacun de leur propre clé pour des déploiements distincts.

Générer une clé API

La génération s’effectue depuis la définition d’un agent du canal Widget externe.

1. Ouvrez REDA AI depuis le lanceur d’applications Salesforce.
2. Ouvrez les définitions d’agents, puis l’agent configuré pour le Widget externe.
3. Repérez la carte Clé API externe. Son emplacement dépend de la page d’enregistrement ; elle indique si une clé est déjà configurée.
4. Cliquez sur Générer une clé API. Le service enregistre la nouvelle empreinte et affiche la clé complète une seule fois. Si une clé existe déjà, la régénération la remplace après confirmation.
5. Copiez immédiatement la clé dans un emplacement adapté à votre processus de déploiement. Après fermeture de l’affichage, ce parcours ne permet pas de récupérer la clé complète.
6. Vérifiez la réussite de la génération. L’action enregistre elle-même la nouvelle empreinte ; aucun clic supplémentaire sur Enregistrer n’est nécessaire pour activer la clé. Préparez ensuite la mise à jour du widget.

Génération d’une clé API depuis la définition d’un agent.

Utiliser la clé API

Intégrer le widget externe

Renseignez la clé et l’URL du point d’accès Salesforce dans le script d’intégration. La clé utilise l’attribut data-api-key. Voir Configurer le widget externe pour l’exemple complet et les autres attributs.

Remplacez les valeurs d’exemple par la clé générée et l’URL de votre organisation. Vérifiez ensuite l’ouverture d’une session et un message de test depuis le site prévu.

Limiter les origines autorisées

Le champ Origines autorisées de l’agent contient une liste d’origines séparées par des virgules, par exemple https://www.example.com, https://app.example.com.

À l’ouverture d’une session, le service compare l’en-tête Origin à la liste configurée. Dans le parcours vérifié, une liste vide autorise toutes les origines ; avec une liste renseignée, une origine absente ou non autorisée est refusée. Ce contrôle a les limites suivantes :

• Clé visible : la liste réduit les usages depuis d’autres sites dans un navigateur, mais un client serveur peut fournir un en-tête d’origine. Elle ne constitue pas une authentification forte du client.
• Intégration sur un autre site : un navigateur fournit l’origine de la page. Le contrôle initial peut refuser une origine non autorisée, mais les appels de session ultérieurs ne revérifient pas tous cette origine. Protégez également les jetons de session et limitez les permissions et l’usage.

Configurer les origines autorisées

1. Ouvrez la définition de l’agent Widget externe.
2. Repérez le champ Origines autorisées.
3. Saisissez les origines séparées par des virgules, avec le protocole et le port lorsqu’il est nécessaire, par exemple https://www.example.com, https://support.example.com.
4. Enregistrez et testez une nouvelle session depuis une origine autorisée puis une origine non autorisée. La modification ne constitue pas une révocation générale des sessions déjà ouvertes.

Débit et maîtrise des crédits

Plusieurs contrôles limitent les appels du widget. Distinguez les champs de l’agent du plafond global :

Adaptez ces paramètres au trafic et au budget de l’organisation. Augmenter un débit autorisé peut accroître la consommation ; un plafond quotidien global, le solde de crédits et les limites de session répondent à des besoins différents.

Révoquer et remplacer une clé

Quand révoquer une clé

Une révocation peut être nécessaire dans les cas suivants :

• Vous suspectez un usage non autorisé.
• Vous souhaitez arrêter un ancien déploiement.
• Vous appliquez la politique de remplacement des clés de votre organisation.
• Vous devez retirer un accès opérationnel précédemment confié à un collaborateur.

Révoquer une clé

1. Ouvrez la définition de l’agent Widget externe.
2. Dans la carte Clé API externe, cliquez sur Révoquer la clé API.
3. Lisez la demande de confirmation et confirmez la révocation si elle correspond au changement prévu.
4. Après réussite de l’action, la clé stockée est supprimée. Les appels suivants qui présentent cette ancienne clé échouent à la validation.

Remplacer une clé

Préparez une fenêtre de changement adaptée : le remplacement ne garantit pas une absence d’interruption.

1. Générez la nouvelle clé sur l’agent et copiez-la. La régénération remplace l’ancienne dès sa réussite.
2. Mettez rapidement le widget à jour avec la nouvelle clé, selon votre processus de déploiement autorisé.
3. Actualisez et vérifiez les clients. Contrôlez les caches, les pages déjà ouvertes et une nouvelle session. Les clients restés sur l’ancienne clé échoueront jusqu’à leur mise à jour.
4. Vérifiez la clé active et le fonctionnement du site. Ne cliquez pas ensuite sur Révoquer pour supprimer « l’ancienne » clé : cette action supprimerait la nouvelle clé active.

Cette procédure coordonne le remplacement de l’unique clé. Elle ne fournit ni délai de grâce pour l’ancienne clé ni garantie de continuité des sessions ouvertes.

Stockage et protection des clés

Stockage dans le package

Le parcours actuel ne conserve pas la clé brute dans le champ de l’agent. Il y enregistre une empreinte SHA-256 avec un sel aléatoire propre à l’enregistrement, au format {nonce}:{hash}. Le calcul inclut également le contexte de l’organisation et du service. Cette valeur n’est pas une copie déchiffrable de la clé.

La clé complète est affichée une seule fois lors de sa génération. Ce parcours ne permet pas de la relire depuis le champ ou l’interface ; si elle est perdue, il faut la remplacer. Les copies déjà intégrées à votre site restent naturellement lisibles dans ce site.

Limiter les copies et les accès

Gérez la clé selon sa fonction et sa visibilité dans le widget public :

• Évitez les copies inutiles dans les dépôts : utilisez votre processus de configuration pour ne pas multiplier les clés dans l’historique du code.
• Centralisez la configuration : un gestionnaire de configuration ou une variable d’environnement peut faciliter le déploiement et le remplacement. Cela ne rend pas secrète la valeur finalement envoyée au navigateur dans le widget.
• Partagez-la par le canal prévu : utilisez le processus de partage sécurisé de votre organisation pour les échanges opérationnels nécessaires.
• Contrôlez les droits de gestion : vérifiez qui peut modifier la définition de l’agent, générer ou révoquer sa clé et changer ses permissions ou limites.
• Remplacez-la selon votre politique : définissez la fréquence et le processus avec votre organisation, en tenant compte de l’interruption possible et des mises à jour de tous les clients.

Résoudre les problèmes de clé

Le widget renvoie « Unauthorized » ou « Invalid API Key »

Causes à vérifier :

• Clé incorrecte : comparez la configuration déployée avec la valeur copiée. Vérifiez les caractères manquants et les espaces superflus.
• Clé révoquée ou remplacée : vérifiez l’état de la carte et le dernier changement. Une clé active n’est pas affichée en clair ; son absence à l’écran ne prouve pas une révocation.
• Origine refusée : vérifiez l’origine exacte et le champ Origines autorisées. Modifiez la liste uniquement si ce site doit être autorisé.
• Format ancien ou configuration absente : vérifiez l’avertissement de migration et l’état de la clé. Le parcours décrit ne prévoit pas d’expiration automatique liée à une date ; ne concluez pas à une expiration à partir d’un champ vide.

Le widget indique un dépassement de limite

Causes à vérifier :

• Débit horaire : examinez la limite de l’agent et le trafic cumulé. Réduisez la fréquence ou ajustez la limite si le budget et l’usage le justifient.
• Débit par session : il s’agit d’une fenêtre par minute. Attendez la fin de la fenêtre et réduisez la cadence ; créer de nouvelles conversations n’est pas une solution pour contourner les contrôles.
• Plafond quotidien : vérifiez le plafond global des usages externes et le solde disponible. Une recharge augmente le solde mais ne relève pas ce plafond. Un administrateur autorisé peut ajuster le réglage, ou attendre la réinitialisation quotidienne applicable.

Le widget indique « Authentication failed »

Causes à vérifier :

• La clé intégrée au site ne correspond plus à la clé active de l’agent.
• La clé a été révoquée ou remplacée après le déploiement.
• L’agent a été supprimé, désactivé ou n’utilise plus le canal attendu.

Vérifiez l’état de l’agent et la configuration du client, puis remplacez et redéployez la clé uniquement si nécessaire.

Questions fréquentes