Clés API
Une clé API permet au site, à l'application ou à votre serveur de travailler avec le projet sans passer par l'interface : envoyer des événements, lire des profils, gérer des segments, des parcours et des campagnes. Les clés se créent et se révoquent dans « Paramètres » → « Clés API ».
La section est visible par le « Propriétaire », l'« Administrateur » et le « Gestionnaire ». Seuls le « Propriétaire » et l'« Administrateur » peuvent créer et révoquer des clés.
Types de clés
| Écriture | Secrète | |
|---|---|---|
| Commence par | cdp_wk_ |
cdp_sk_ |
| Ce qu'elle permet | uniquement l'envoi d'événements | l'envoi d'événements et des actions dans le projet selon les autorisations choisies |
| Où l'utiliser | code du site, application mobile, serveur | uniquement votre serveur |
| Peut être visible par des tiers | oui, elle figure dans le code des pages du site | non, gardez-la secrète |
| Limite de requêtes | 6000 par minute | 1200 par minute (par défaut) |
La clé d'écriture est publique par nature : elle figure dans le code de chaque page du site. Elle ne permet que d'envoyer des événements, sa fuite ne donne donc pas accès aux données. Pour qu'un site tiers ne puisse pas envoyer d'événements en votre nom, vous pouvez indiquer dans la section « Site web » les domaines depuis lesquels la clé est acceptée : voir Connexion du site.
La clé secrète donne un accès serveur aux données du projet. Ne l'insérez jamais dans le code des pages, dans des applications mobiles ni dans des dépôts publics.
Créer une clé
- Ouvrez « Clés API ».
- Dans la carte « Nouvelle clé », saisissez un « Nom » qui vous permettra de savoir plus tard où la clé est utilisée, par exemple « Site web » ou « Serveur de la boutique en ligne ».
- Choisissez le « Type » : Écriture ou Secrète.
- Pour une clé secrète, cochez les « Autorisations de la clé » : uniquement ce dont l'intégration a réellement besoin.
- Cliquez sur « Créer la clé ».
Juste après la création, la clé complète s'affiche en haut de la page. Cliquez sur « Copier » et conservez-la, par exemple dans un gestionnaire de mots de passe ou dans les variables d'environnement du serveur. La clé secrète n'est affichée qu'une seule fois : nous n'en conservons qu'une empreinte et elle ne peut pas être récupérée. Si vous l'avez perdue, créez-en une nouvelle et révoquez l'ancienne.
Il est plus pratique de créer la clé d'écriture du site directement dans la section « Site web » : elle y est insérée automatiquement dans le code d'installation et reste disponible à tout moment (voir Connexion du site).
Le tableau des clés indique le nom, qui l'a créée et quand, le type, le début de la clé (par exemple cdp_sk_a1b2…), le nombre d'autorisations et la date de dernière utilisation.
Autorisations de la clé secrète
Vous ne pouvez accorder à une clé que les autorisations dont vous disposez vous-même. Les autorisations s'appliquent à tout le projet : il est impossible de limiter une clé à certains parcours ou segments.
| Autorisation | Ce qu'elle ouvre |
|---|---|
| Lire les profils | un profil par identifiant et ses événements |
| Données personnelles non masquées | e-mail, téléphone et autres données personnelles en clair ; sans cette autorisation, elles sont masquées |
| Modifier les profils et les consentements | consentements aux envois, liaison Telegram |
| Supprimer des profils (RGPD) | suppression d'un profil à la demande du client |
| Catalogue des événements et des attributs | liste des événements et des propriétés des profils |
| Lire les segments / Modifier les segments | consultation, création, modification, suppression et recalcul des segments |
| Lire les parcours et les rapports ; Modifier les brouillons et inscrire des participants ; Publier, mettre en pause et archiver les parcours | travail avec les parcours |
| Lire les campagnes et les rapports ; Créer et modifier des campagnes ; Lancer, mettre en pause et annuler des campagnes | travail avec les campagnes |
| Lire le catalogue de produits et les recommandations ; Charger et supprimer des produits | produits et recommandations |
| Analytique | rapports |
Exemple : une clé destinée à synchroniser les clients VIP depuis un CRM n'a besoin que des autorisations « Lire les segments » et « Modifier les segments ».
Toutes les actions effectuées avec une clé secrète sont consignées dans le journal d'audit du projet au nom de la clé : voir Paramètres du projet, forfait et audit.
Révoquer une clé
- Trouvez la clé dans le tableau et cliquez sur « Révoquer ».
- Confirmez l'action.
Les requêtes utilisant cette clé cessent immédiatement de fonctionner (réponse 401). La clé révoquée reste dans la liste avec la mention « Révoquée » afin de conserver son historique. Elle ne peut pas être réactivée : si nécessaire, créez-en une nouvelle.
Révoquez une clé sans attendre si elle a pu tomber entre de mauvaises mains, si un collaborateur qui y avait accès a quitté l'entreprise ou si l'intégration n'est plus utilisée.
À savoir
- Limites. En cas de dépassement de la limite de requêtes ou du quota mensuel d'événements du forfait, l'API répond
429. Répartissez les envois de façon régulière et réessayez après une pause. - Remplacement sûr d'une clé. Créez une nouvelle clé, mettez-la à jour sur le serveur, vérifiez que les requêtes passent (champ « Dernière utilisation »), puis seulement révoquez l'ancienne.
- Une clé distincte par intégration. Ainsi, le journal d'audit montre qui a fait quoi, et en cas de fuite il suffit de révoquer une seule clé.
- Pour envoyer des événements et appeler l'API depuis un serveur, consultez l'article Intégration côté serveur.